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1.  INTRODUCTION 

This  manual  is  to  introduce  the  user  to  the  Xgbm  program  and  its  associated  module 
GBseis .  The  two  programs  in  tandem  are  designed  to  allow  the  user  to  create  and  mani¬ 
pulate  intricate,  laterally  heterogeneous,  two  dimensional  (2-D)  velocity  models  of  the 
Earth’s  interior  and  then  to  compute  synthetic  seismograms  for  those  models  using  Gaus¬ 
sian  beams.  The  user  is  referred  to  Weber  (1988a)  for  an  outline  of  the  theory  of  Gaus¬ 
sian  beams  as  implemented  here  and  a  definition  of  some  of  the  terms  used  throughout 
this  manual. 

Xgbm  and  GBseis  may  be  run  either  in  conjunction  with  the  ISIS  interprocess  com¬ 
munication  (IPC)  software  available  at  the  Center  for  Seismic  Studies  (CSS),  a  second  IPC 
module  distributed  with  the  Xgbm  package,  or  as  stand-alone  programs.  If  either  of  the 
IPC  software  packages  is  utilized,  interaction  with  the  geotool  data  analysis  program  is 
possible,  provided  one  is  using  geotool  version  vl.2  or  higher.  The  software  has  recently 
been  modified  to  interface  with  the  Geographic  Information  System  (GIS)  at  CSS. 

The  code  is  based  on  Fortran  programs  originally  written  by  Michael  Weber  of  the 
Seismologisches  Zentralobservatorium  Grafenberg,  Erlangen,  Germany.  Under  contract 
F29601-91-C-DB04  from  Phillips  Laboratory  and  monitored  by  DARPA,  Principal  Investi¬ 
gators  Peter  Davis  and  Ivan  Henson  translated  the  original  Fortran  into  C  and  constructed 
around  it  a  graphics  shell  of  C  and  Motif©-based  X-Windows  widgets,  so  that  what  earlier 
required  user  Siting  of  large  data  files  could  now  be  accomplished  with  graphics  tools. 
This  distribution  was  compiled  on  a  Sun  4/360S  running  OS  4.1.3  and  XI 1  Release  5. 
Groups  at  the  Ruhr  University,  Southern  Methodist  University,  the  Oklahoma  Geological 
Survey,  and  the  GFZ  Potsdam  report  they  have  successfully  executed  version  1.0.2  of 
these  programs  at  their  installations.  In  several  instances,  the  code  has  run  successfully 
under  OpenWindows  as  well,  but  this  required  minor  modifications  to  the  binaries  because 
of  the  non-standard  location  of  X  resource  files  specified  at  compilation. 

A  number  of  tests  of  the  system’s  accuracy  in  both  traveltime  calculation  and 
waveform  synthesis  have  been  conducted.  The  results  of  these  checks  are  described  in 
Davis  and  Henson,  (1993).  Generally  speaking,  the  new  code  is  as  accurate  as  the  origi¬ 
nal  Fortran,  which  was  itself  carefully  checked  against  reflectivity  and  finite  difference 
codes. 

The  next  section  contains  a  brief  outline  of  the  underlying  concepts  of  the  system. 
There  follow  several  sections  explaining  how  to  initiate  the  programs,  some  example 
tutorial  sessions  describing  how  to  accomplish  common  tasks,  and  a  detailed  description  of 
the  action  of  each  button  and  display  in  the  graphics  module  Xgbm .  Because  it  has  not 
been  possible  to  eliminate  all  shortcomings,  a  section  is  included  in  which  known  bugs  are 
described.  For  those  who  wish  to  read  journal  articles  relating  research  in  which  the  origi¬ 
nal  Weber  code  was  used,  references  are  listed  at  the  end.  So  that  developers  might 
exploit  the  modular  design  of  the  system,  two  appendices  have  been  added  in  which  the 
format  of  IPC  messages  and  of  inpui/output  files  are  detailed. 

Questions  and  comments  may  be  directed  to  the  authors  (davis@seismo.CSS.GOV 
and  ihenson@seismo.CSS.GOV).  The  authors  will  respond  as  time  and  resi^arces  permit. 
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Bug  reports  will  be  posted  within  the  same  ftp  directory  on  seismo.CSS.GOV  from  which 
this  package  is  available. 

2.  BACKGROUND 

2.1  Functional  Flow 

The  functional  flow  for  computing  Gaussian  beam  seismograms  and/or  calculating 
traveltimes  through  heterogeneous  media  is  simple: 

(1)  model  input  or  creation, 

(2)  source-receiver  geometry  and  component  phase  specification, 

(3)  dynamic  raytracing, 

(4)  traveltime  and  /or  seismogram  computation,  and 

(5)  display  of  results. 

Step  one  is  to  use  Xgbm  either  to  create  an  input  model  from  scratch  or  to  access  a  fully 
two-dimensional  model  which  has  been  created  previously.  The  former  is  generally  done 
by  beginning  with  a  one-dimensional  (1-D)  model  and  extending  it  into  a  second  dimen¬ 
sion.  Once  in  this  extended  form  the  user  may  impose  large-scale  heterogeneity,  such  as  a 
subduction  zone  in  the  case  of  a  global  model,  or  a  localized  heterogeneity,  such  as  a  sedi¬ 
mentary  basin  with  low-velocity  lens  in  the  case  of  a  regional  model.  Additional  hetero¬ 
geneity  may  be  created  by  manipulating  the  model  elements  manually  with  a  mouse. 
Whether  created  ab  initio  or  read  in  and  modified,  the  model  may  be  stored  for  future  use 
at  the  end  of  this  step. 

The  velocity  model  is  specified  as  a  series  of  knotpoints  and  triangles.  Each  knot- 
point  fixes  Vp ,  V, ,  and  p  at  a  point  in  space.  Because  the  velocity  gradient  is  assumed  to 
be  linear  between  each  knotpoint,  the  velocity  is  effectively  specified  fully  in  two  dimen¬ 
sions.  (One  exception  is  at  discontinuities:  there  two  knotpoints  are  spatially  co-located 
and  specify  the  velocity  and  density  on  each  side  of  the  discontinuity.)  Knotpoints  are 
grouped  into  triplets  to  form  triangles.  A  value  for  and  Q^,  the  P-  and  5 -wave 
attenuation,  is  assigned  to  the  space  enclosed  by  each  triangle.  Xgbm  tracks  which  trian¬ 
gles  share  knotpoints  and  are  therefore  "neighbors." 

Under  these  linear  gradient  conditions,  there  is  an  analytical  solution  for  the  raypath 
across  a  triangle.  Once  the  position  of  the  source  has  been  specified  and  the  phases  to  be 
traced  have  been  chosen  (step  two),  raytracing  through  the  model  (step  three)  is  accom¬ 
plished  by  tracing  stepwise  analytically  through  each  component  triangle  along  the  ray- 
path.  Anelasticity  is  accounted  for  by  computing  at*  operator  using  Qa  ^he 

triangles.  Results  from  this  step  are  also  stored  for  later  use  by  GBseis.  Note  that 
receiver  position  information  is  not  essential  at  this  point  and  is  not  written  out  with  the 
other  raytracing  information.  The  user  usually  finds  it  convenient,  however,  to  input  this 
information  at  the  same  time  the  source  is  positioned. 

The  essentials  for  step  four,  traveltime  calculation  or  seismogram  computation,  are 
now  complete.  In  the  Gaussian  beam  method,  it  is  not  necessary  to  compute  rays  which 
travel  directly  from  source  to  receiver.  Rather,  it  is  sufficient  to  compute  a  number  of 
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rays  which  originate  at  the  source  and  terminate  within  several  wavelengths  of  the 
receiver.  It  is  possible  to  generate  a  traveltime  curve  without  specifying  the  receiver  posi¬ 
tion.  However,  to  obtain  a  seismogram,  one  must  first  specify  precisely  the  position  of  the 
receiver  relative  to  the  source.  The  seismogram  consists  of  a  weighted  sum  of  rays  which 
terminate  within  the  required  wavelength  limit  of  the  receiver.  Traveltimes  for  distances 
not  corresponding  to  a  ray  endpoint  are  found  by  using  slowness  to  extrapolate  the  travel¬ 
time  of  the  nearest  terminating  ray. 

The  computed  synthetic  seismograms  are  written  out  in  CSS  3.0  schema  format. 
Step  five,  the  display  of  results,  is  not  possible  with  the  software  modules  provided  in  this 
package.  Programs  to  display  CSS  format  data  or  to  translate  it  into  other  formats  may  be 
obtained  by  contacting  the  CSS  staff. 

One  aspect  about  the  velocity  model  presentation  needs  to  be  clarified.  Xgbm  is 
capable  of  displaying  a  model  in  two  modes,  flattened  and  spherical.  The  default  mode, 
flattened,  shows  the  model  after  its  coordinates,  velocities  and  densities  have  been  passed 
through  a  transformation  governed  by  the  earth  flattening  approximation  (EFA).  The  par¬ 
ticular  transformation  in  use  here  is  the  one  suggested  by  Muller  (1977).  There  is  a  limit 
near  the  Earth’s  center  where  this  EFA  is  no  longer  valid.  A  lower  bound  on  depth 
corresponding  to  this  breakdown  point  has  been  installed  in  the  program.  The  user  will 
discover  that  any  attempt  to  set  the  depth  lower  than  the  EFA  breakdown  point  (about  800 
km  from  the  center)  will  fail. 

Use  of  the  EFA  is  evident  in  a  second  way.  When  the  user  looks  at,  or  edits,  the 
text  widget  showing  the  source  depth,  that  value  is  always  expressed  in  unflattened  coordi¬ 
nates,  no  matter  what  the  display  is.  If  the  display  is  currently  flattened,  it  will  be 
apparent  that  the  source  position  in  the  display  will  be  different  than  that  indicated  in  the 
text  widget.  The  two  values  are  related  by 

z'  =  R  In 

R  —  z 

where  z  and  z'  are  the  unflattened  and  flattened  depths,  respectively,  and  R  is  the  earth’s 
radius. 

The  newest  and  potentially  most  useful  feature  of  Xgbm  is  the  program’s  ability  to 
make  use  of  surface  topography  and  depth-to-moho  information  contained  in  geographic 
databases  and  available  through  raster  server  programs  such  as  described  by  Fielding  et  al. 
(1992).  The  module  gc_raster  acts  as  an  interface  with  raster  server  programs  in  other 
systems  and  formats  the  output  for  use  by  Xgbm .  Details  of  how  this  works  are  provided 
in  Section  5.6. 


2.2  System  Architecture 

This  brief  sub.section  describes  how  the  above  tasks  are  divided  between  the  modules 
Xgbm  and  GBseis .  Both  are  designed  to  run  either  by  exchanging  interprocess  communi¬ 
cation  messages  (IPC  mode)  or  through  flat  files  (non-IPC  mode).  See  Section  4  to  learn 
how  to  initiate  the  system  in  the  two  different  modes.  The  details  of  IPC  message  format 


-  2,  - 


Version  1.1 


are  elaborated  in  Appendix  A.  The  contents  of  all  files  are  explained  in  Appendix  B. 

Xgbm  handles  all  velocity  model  manipulation  and  acts  as  the  hub  of  all  IPC  com¬ 
munication.  Source-receiver  geometry  may  be  set  either  by  Xgbm  graphics  (non-IPC)  or 
by  IPC  messages  received  by  Xgbm .  In  limited  cases,  phases  to  be  traced  are  selected  via 
IPC  messages  as  well,  but  in  general,  the  user  should  select  the  phases  using  Xgbm  lists. 
All  raytracing  is  performed  by  Xgbm .  Once  the  raytracing  results  are  written  to  an  output 
file,  seismograms  and/or  traveltimes  may  be  obtained  in  either  mode  from  GBseis.  For 
convenience,  Xgbm  may  be  used  to  specify  the  source-time  function  and  source  type,  but 
this  is  not  necessary. 

3.  INSTALLATION 

Version  1.1  of  Xgbm  and  GBseis  are  distributed  as  a  compressed  tar  file 
tar.Xgbm.vl.l.Z.  This  should  be  moved  to  the  directory  where  one  wishes  these  programs 
to  reside  and  where  they  will  be  accessible  to  everyone  who  wishes  to  use  them.  In  this 
example,  that  directory  will  be  called  "/voodoo”.  The  UNIX  command  to  move  the  file  is 

mv  tar.Xgbm.vl.l.Z  /voodoo 
Now  move  to  /voodoo  and  uncompress  the  file: 

cd  /voodoo;  uncompress  tar.Xgbm.vl.l 
Finally  unpack  the  tar  file; 

tar  xvf  tar.Xgbm.vl.l 

There  should  now  be  two  directories,  one  named  bin  and  one  named  vmodels.  The  former 
contains  the  executable  binaries  Xgbm  and  GBseis  that  perform  velocity  model  manipula¬ 
tion  and  compute  synthetic  seismograms,  and  in  addition,  a  binary  called  ipcc  used  for 
interprocess  communication.  The  X  resources  for  the  graphics  module  Xgbm  are  found  in 
the  XI 1  subdirectory  of  bin.  The  directory  vmodels  contains  ASCII  files  of  velocity 
models  in  a  format  capable  of  being  read  by  Xgbm .  Please  do  not  edit  them,  but  do  feel 
free  to  copy  them  as  examples  of  files  in  a  format  Xgbm  can  input.  The  binaries  have 
been  compiled  on  a  Sun  SPARC  running  SunOS  Release  4.1.3.  You  will  also  require  X- 
Windows,  but  no  dynamic  libraries. 

The  files  should  now  be  positioned  correctly  in  your  system.  Please  add  the  bin 
directory  to  your  path.  This  is  best  done  by  editing  your  .cshrc  file,  but  may  be  accom¬ 
plished  temporarily  by  typing: 

set  path  =  ($path  /voodoo/bin) 

Finally,  edit  the  file  /voodoo/bin/Xll/XgbmMain.  Everywhere  the  directory  path 
lusrllcontractsIlbOOIsrcPCl II  appears,  please  substitute  /voodoo/binPClII.  The  installation 
should  now  be  complete.  See  the  next  section  for  how  to  start  the  programs. 

While  the  above  simple  recipe  should  woric,  a  more  satisfying  installation  is  to  move 
the  X  resource  files  from  the  /voodoo/bin/Xll  directory  to  your  system’s  app-defaults 
directory,  commonly  found  in  /usr/lib/Xll.  In  this  case,  everywhere 
lusrl /contracts! 1600lsrc/Xl  1 !  appears,  the  string  /usr/lib/Xl  1 /app-defaults/  should  be  sub¬ 
stituted.  However,  if  you  are  using  OpenWindows,  the  directory  to  which  the  resources 
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should  be  moved  is  not  /usr/lib/Xll/app-defaults  but  more  likelj'  /usr/openwin/lib/Xil. 
Consult  your  system  documentadon  and  OpenWindows  installation  notes  for  which  direc¬ 
tory  to  place  your  resource  files. 

4.  STARTING 

The  program  may  be  run  in  any  two  of  three  different  modes:  IPC  mode  using  ISIS , 
IPC  mode  using  ipcc ,  and  non-IPC  mode.  Which  of  the  two  IPC  modes  your  version  can 
run  is  determined  at  compilation.  A  given  binary  will  run  DPC  ISIS  mode  and  non-IPC 
mode  or  ipcc  IPC  mode  and  non-IPC  mode.  This  section  explains  how  to  start  the  pro¬ 
gram  in  each  different  mode.  Regardless  of  which  mode  one  chooses,  the  following 
environment  variables  should  be  set: 


name 

default 

XENVIRONMENT 

GBMODENV 

GBWORKENV 

7bin/Xl  1/XgbmMain 
./vmodels 

The  default  values  will  be  correct  only  if  you  are  in  directory  /voodoo  where  /voodoo  fol¬ 
lows  the  example  of  the  preceding  section.  The  package  should  work  independent  of 
home  directory  if  the  variables  are  reset  to: 

setenv  XENVIRONMENT  /voodoo/bin/Xll/XgbmMain 
setenv  GBMODENV  /voodoo/vmodels 

The  variable  GBWORKENV  sets  directory  to  which  the  output  files  will  be  written.  If 
one  wishes  to  place  the  files  in  a  directory  other  than  the  one  from  which  the  program  was 
started,  say  /fondue,  then  type: 

setenv  GBWORKENV  /fondue 
and  the  files  will  be  written  to  /fondue. 

The  environment  XENVIRONMENT  need  not  be  set  if  the  Xgbm  resource  files  in 
the  XI 1  subdirectory  of  the  distribution  have  been  moved  to  your  system’s  app-defaults 
directory  during  installation.  One  may  then  personalize  one’s  Xgbm  display  by  recopying 
selective  resources  from  the.se  files  into  the  user’s  .Xresources  file,  editing  them,  and 
loading  these  into  the  window  manager’s  resource  database  xrdb. 

4.1  IPC  ISIS  Mode 

This  is  the  most  appropriate  mode  for  working  in  the  software  environment  which 
exists  at  CSS.  If  you  do  not  have  the  ISIS  package  and  wish  to  obtain  it,  please  contact 
the  CSS  staff.  Some  familiarity  with  ISIS  is  assumed  here,  namely  that  the  user  has  set 
the  environment  variables  ISISPORT  and  AESIRHOST  correctly.  One  must  first  start  an 
agent,  say  foo,  by  typing: 

CommAgent  -a  foo  & 

It  should  connect  promptly.  Now  start  GBseis  with  the  same  agent  name, 
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GBseis  -a  foo  & 

and  geotool  as  well,  if  one  desiies  that  display  capability: 

geotool  -a  foo  & 

Finally,  start  Xgbm : 

Xgbm  -a  foo  & 

A  small  window  should  appear,  by  default,  in  the  upper  left  hand  comer  of  your  screen. 
You  should  resize  it  to  the  size  with  which  you  feel  most  comfortable.  The  -a  flag  used 
when  starting  Xgbm  and  GBseis  forces  the  two  programs  to  run  in  an  IPC  mode  under 
group  foo. 

4.2  IPC  ipcc  Mode 

This  mode  provides  the  ease  of  IPC  communication  without  the  overhead  involved  in 
the  full  ISIS  package.  One  should  first  set  two  environment  variables,  IPCC_PORT  and 
IPCC  HOST.  The  simplest  case,  which  should  suffice  for  a  single  workstation,  is: 

setenv  IPCC  HOST  ‘hostname* 
setenv  IPCC  PORT  2001 

Now  start  ipcc , 

ipcc  & 

and  then  GBseis  and  geotool  if  one  wishes  the  latter  for  display: 

GBseis  -a  & 
geotool  -a  & 

Finally,  start  Xgbm : 

Xgbm  -a  & 

A  small  window  should  appear,  by  default,  in  the  upper  left  hand  comer  of  your  screen. 
You  should  resize  it  to  the  size  with  which  you  feel  most  comfortable.  The  -a  flag  used 
when  starting  Xgbm  and  GBseis  triggers  the  two  programs  to  run  in  an  IPC  mode.  This 
sequence  should  suffice  for  most  cases. 

There  are  other  possible  starting  modes,  however.  In  the  above  example,  it  was 
assumed  for  convenience  that  the  group  name  would  be  the  user  name.  If  for  some  rea¬ 
son,  another  group  name  was  to  be  used,  say  foo,  start  each  with  a  "-a  foo"  commandline 
argument: 

GBseis  -a  foo  & 

Xgbm  -a  foo  & 
geotool  -a  foo  & 

Also,  it  is  only  necessary  to  have  one  instance  of  ipcc  running  on  the  network.  Two  or 
more  instances  may  ran  as  long  as  they  do  not  share  the  same  port,  as  set  through  the 
IPCC_PORT  environment  or  in  the  command  line: 

ipcc  pon=port_number 

If  a  single  instance  of  ipcc  is  running  but  not  on  your  workstation,  connect  to  it  by  setting 
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the  IPCC_HOST  environment  to  the  name  of  the  workstation  on  which  it  is  running. 

4.3  non-IPC  Mode 

This  mode  is  retained  here  for  historical  reasons  and  has  been  subsumed  in  func¬ 
tionality  by  the  ipcc  IPC  mode.  It  is  the  simplest  mode  of  operation,  however,  and  many 
users  will  find  it  sufficient  for  their  purposes.  In  this  case,  GBseis  is  not  run  in  back¬ 
ground  continuously  as  in  the  previous  two  modes.  Rather,  at  each  instance  Xgbm 
requires  that  a  synthetic  seismogram  be  calculated,  Xgbm  writes  an  input  file  (  default  = 
.GBinput)  for  GBseis  to  read  and  then  spawns  GBseis  with  a  system  call.  This  instance 
of  GBseis  is  initiated  with  a  special  flag  that  tells  GBseis  to  obtain  the  necessary  informa¬ 
tion  from  the  input  file,  calculate  the  seismogram  and  then  exit.  To  start  Xgbm  in  non- 
IPC  mode,  type: 

Xgbm  & 

and  a  small  window  should  appear,  by  default,  in  the  upper  left  hand  comer  of  your 
screen.  You  should  resize  it  to  the  size  with  which  you  feel  most  comfortable.  The 
absence  of  the  -a  flag  used  when  starting  Xgbm  triggers  Xgbm  to  run  in  a  non-IPC  mode. 

5.  TUTORIAL  SESSIONS 

This  section  is  intend  to  lead  the  user  through  a  number  of  common  tasks.  The  order 
in  which  they  are  presented,  which  follows  from  the  discussion  in  Section  2,  often  need 
not  be  adhered  to  rigidly.  One  may  read  in  a  model,  trace  rays,  reposition  the  source, 
compute  a  seismogram,  change  the  model  or  source  position  and  then  iterate  on  the  above, 
all  without  difficulty.  Some  sense  of  direction  is  useful  however.  It  is  absurd  to  consider 
tracing  rays  before  one  reads  in  a  velocity  model.  A  more  subtle  (but  critical)  point  is  to 
remember  to  write  out  the  raytracing  results  before  attempting  to  compute  a  seismogram 
based  upon  that  raytracing. 

The  user  is  assumed  to  be  familiar  with  X-Windows  and  how  to  operate  its  common 
widgets:  push  buttons,  toggle  buttons,  sliders,  and  lists.  Assuming  that  the  button  bindings 
have  not  been  altered  in  any  way,  selection  is  usually  accomplished  with  single  click  of 
the  left  mouse  button.  By  convention,  Ctrl-l^t  refers  to  the  action  of  simultaneously 
depressing  the  Control  key  and  clicking  the  left  mouse  button,  Ctrl-middle,  to  simultane¬ 
ously  depressing  Control  and  clicking  the  middle  mouse  button,  etc. 

This  section  does  not  illustrate  all  the  package’s  capabilities.  The  reader  is  urged  to 
browse  through  Section  7  after  becoming  familiar  with  the  basic  operation. 

5.1  Model  Manipulation 

The  principal  design  goal  of  this  project  was  to  create  a  graphics  tool  to  allow  the 
user  to  construct  quickly  and  easily,  complicated  2-D  models  of  seismic  velocity.  Hence 
these  capabilities  of  Xgbm  go  to  the  heart  of  the  software  package.  The  first  window 
presented  to  the  user  looks  like  this: 
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5.1.1  Model  input 

Select  the  F\Lt,  button  from  the  Main  menu  bar.  A  pulldown  should  appear  contain¬ 
ing  the  buttojis  INPLT,  SAVE,  WRITE,  and  QUIT.  Select  INPUT.  A  further  pulldown 
should  appear  containing  buttons  STANDARD  and  USER-DEFINED.  As  their  names 
imply,  STANDARD  is  used  to  read  in  standard  models  distributed  with  the  software. 
USER-DEFINED  is  used  to  read  in  models  created  by  the  user  in  previous  work  sessions. 

5. 1.1.1  Model  input  —  standard  models 

Select  STANDARD.  A  popup  like  this  should  appear: 


Version  LI 


On  the  left-hand  side  are  two  lists  entitled  "Regional"  and  "Global."  The  regional  models 
are  two  layer  crusts  over  a  half-space.  The  global  models  are,  in  general,  models  either 
published  as  such  or  derived  from  travel  time  tables.  See  Appendix  C  for  details.  The  abr 
and  orig  following  herrin  refer  to  abridged  (smoothed  over  depths  where  the  velocity  gra¬ 
dient  was  small)  and  original,  respectively.  For  now,  select  Jb.  The  plots  of  Vp ,  and  p 
as  a  function  of  depth  should  appear: 


To  create  a  2-D  model,  it  is  necessary  to  specify  the  depth  (the  maximum  depth  to 
which  model  extends),  breadth  (horizontal  distance  model  extends),  and  resolution  (how 
widely  spaced  the  knotpoints  are).  One  controls  the  lower  depth  bound  on  the  model  in 
one  of  two  ways.  The  first  is  by  moving  the  horizontal  line  segment  which  appears  in  all 
three  of  the  velocity/density  plots.  If  you  have  selected  ib,  it  should  appear  near  the  half¬ 
way  point  of  the  model  at  3186  km.  You  can  alter  this  bottom  depth  by  moving  the 
pointer  into  the  display  (either  the  velocity  plots,  density  plot  or  the  space  between  them), 
depressing  and  holding  down  the  left  mouse  button,  and  moving  the  mouse  up  and  down 
the  screen.  The  depth  at  which  you  release  the  mouse  will  be  the  lower  model  bound. 
The  second  way  to  control  the  bound  is  through  the  text  widget  labeled  Depth  in  the  lower 
left-hand  comer.  As  one  slides  the  horizontal  bar  up  and  down,  the  value  in  this  text 
widget  is  updated.  One  can  edit  the  text  widget  to  change  the  depth.  Move  the  pointer 
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into  the  depth  text  widget  (the  rectangle  to  the  right  of  the  Depth  label)  now  and  double 
click  on  the  left  mouse  button.  The  widget  should  display  in  reverse  video.  If  you  now 
hit  the  delete  key,  the  entry  should  become  blank.  Type  in  a  new  value  for  the  lower 
bound,  say  6200.  [If  you  prefer  to  work  in  radius  rather  than  depth,  this  is  also  possible. 
Move  the  cursor  to  the  label  Depth  and  depress  and  hold  the  left  mouse  button.  A  pull¬ 
down  will  appear  containing  Depth  and  Radius.  Slide  the  pointer  onto  the  word  Radius 
and  then  release  the  left  mouse  button.  The  displays  will  revise  themselves  to  be  func¬ 
tions  of  radius.  You  can  toggle  back  and  forth,  the  model  lower  limit  will  be  the  same.] 
Depending  upon  the  resolution  of  your  display,  the  depth  value  displayed  to  the  left  of  the 
movable  horizontal  bar  may  not  agree  precisely  with  the  value  of  the  depth  text  widget 
because  of  round-off.  The  program  always  set  the  lower  depth  bound  on  the  basis  of  the 
text  widget’s  value. 

You  now  must  set  the  breadth,  which  is  done  with  the  widget  labeled  Km  in  the  bot¬ 
tom  middle  of  the  popup.  This  text  widget  should  have  the  peculiar  value  of  40030.174, 
the  number  of  km  for  the  circumference  of  an  earth  of  radius  6371  km.  One  sets  the 
latertd  extent  of  the  model  by  editing  this  value  in  the  same  fashion  as  one  edited  the 
Depth  text  widget.  When  working  with  teleseimic  body  phases,  it  is  perhaps  more  natural 
to  work  in  degrees.  Like  the  DepthJRadius  toggle.  Km  may  be  toggled  between  Km  and 
Degrees.  Toggle  this  button  to  degrees  now.  The  text  widget  should  update  to  360.00, 
the  number  of  degrees  in  circumference.  Leave  the  value  at  360  for  the  time  being. 

Finally,  it  is  necessary  to  set  the  resolution  with  the  Horizontal  Knots  widget  in  the 
lower  right-hand  side.  This  is  done  by  editing  the  value  in  the  rectangle  to  the  right  of  the 
label.  The  number  100  there  now  reflects  the  number  of  horizontal  knots  in  the  grid 
which  will  form  the  2-D  model.  (This  will  become  more  apparent  in  a  moment)  Gen¬ 
erally  speaking,  the  larger  the  number  of  knots,  the  finer  the  resolution,  but  the  longer  the 
program  execution.  The  number  of  vertical  knots  is  not  controllable  from  this  popup,  but 
is  instead  set  by  the  depth  points  at  which  one  specifies  the  model  parameters.  The  raw 
1-D  files  from  which  the  plots  in  this  popup  are  created  are  contained  in  files  in  the  Ivmo- 
dels  subdirectory.  Please  do  not  edit  or  rename  these  files  -  proper  execution  depends 
upon  them  remaining  where  they  are  as  they  are. 

Clearly  the  larger  the  number  of  horizontal  knotpoints,  the  shorter  the  horizontal  tri¬ 
angle  sides.  Again  in  general  one  should  not  have  a  horizontal  side  which  exceeds  the 
shortest  vertical  triangle  side  by  a  factor  of  200  or  greater.  Examination  of  the  data  file 
/vmodels/GB.jb  indicates  that  the  shonest  vertical  segment  for  the  jb  model  is  15  km. 
Therefore  the  shortest  horizontal  segment  should  be  300  km  (2.7  ),  so  for  a  jb  model  of 
breadth  360  ,  the  minimum  number  of  knots  required  is  134.  In  order  to  illustrate  some  of 
Xgbm ’s  behavior,  violate  this  constraint  by  entering  the  number  15. 

The  model  is  now  ready.  Press  the  Apply  button  in  the  lower  left-hand  corner.  (Had 
you  changed  your  mind  at  any  point,  you  could  have  pressed  Hide  instead  and  the  popup 
would  have  disappeared.)  When  you  press  Apply,  two  things  will  happen.  First  the 
"Xgbm  Model  Choice"  popup  will  disappear  and  second,  the  space  below  the  main  menu 
bar  which  had  been  blank  before  is  filled  with  a  grid  of  triangles.  You  may  need  to  resize 
the  window  to  see  a  display  like  this: 
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The  horizontal  scale  extends  to  just  beyond  40,000  km,  the  vertical  scale,  to  just  below 
12,000  km.  This  is  the  jb  model  in  the  default  "earth  flattened"  display  showing  all  con¬ 
stituent  triangles.  The  lower  limit  of  6200  km  has  been  transformed  to  a  value  greater 
than  12,000,  but  because  6200  is  closer  than  800  km  from  the  center,  the  actual  lower 
limit  is  set  to  the  transformed  value  of  (6371-800).  See  the  note  about  the  EFA  in  Section 
2.1  above.  Ordinary  triangle  sides  are  shown  in  black,  sides  where  the  velocity  increases 
discontinuously,  in  red.  Exactly  where  the  discontinuities  are  becomes  more  apparent 
when  one  toggles  off  the  triangle  display.  To  do  this,  press  the  VIEW  button  in  the  main 
menu  bar,  and  when  the  pulldown  appears,  click  on  the  TRIANGLES  toggle  button.  The 
display  should  change  -  the  triangles  will  disappear 


-  11  - 


Version  1.1 


leaving  only  four  horizontal  red  lines  and  two  horizontal  violet  lines  (the  top  and  bottom 
lines).  The  violet  lines  represent  model  boundaries,  the  red  lines,  discontinuities  at  the 
inner  core-outer  core  boundary,  the  core-mantle  boundary,  the  Moho,  and  the  Conrad. 
Had  you  had  set  the  breadth  of  your  model  to  be  anything  less  than  360  ,  there  would  also 
be  two  vertical  violet  lines  marking  bounds  to  the  left  and  right  of  your  model.  It  would 
then  be  impossible  to  model  phases  that  travel  distances  greater  than  360°. 

To  make  this  more  apparent,  change  the  form  of  the  display  by  selecting  VIEW  again 
but  click  this  time  on  FLATTEN.  The  display  will  revise  to 


show  a  series  of  concentric  15-sided  polygons  which  approximate  circles.  All  calculations 
are  done  in  the  flattened  model  however.  Later  in  this  tutorial,  when  phases  are  plotted 
for  this  15  sided  earth,  it  will  be  apparent  that  the  rays  do  not  terminate  along  the  triangle 
sides.  The  traveltimes  are  nevertheless  accurate! 

5. 1.1.2  Model  input  —  user-defined  models 

Select  USER-DEFINED.  A  file  selection  box  entitled  "User-defined  Models"  will 
appear.  Any  file  in  your  current  working  directory  ending  in  ".gb"  should  appear  in  the 
list  on  the  right.  By  convention,  user-defined  models  end  in  this  suffix.  Edit  the  filter  text 
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widget  at  the  top  to  indicate  the  path  where  you  have  installed  the  /vmodels  subdirectory. 
In  the  installation  example,  this  was  /voodoo/vmodels,  so  the  entry  should  be  changed  to 
lvoodoolvnwdels/*.gb.  Then  click  on  the  FILTER  button  <t[  the  bottom.  The  list  at  the 
right  should  include  the  filename  tutorial. gb.  Select  it  by  either  (1)  double-clicking  the 
left  mouse  button  on  the  name,  or  (2)  single  clicking  the  left  mouse  button  (it  will  change 
to  reverse  video)  and  selecting  the  OK  button  at  the  bottom.  In  either  case,  the  popup  will 
disappear  and  the  display  will  indicate  an  irregular  grid  of  triangles  depicting  a  syncline  in 
the  center  with  slight  bowing  up  of  layers  in  the 


mantle  beneath  it.  Had  you  selected  the  CANCEL  button  instead  of  OK,  the  popup  would 
simply  have  disappeared  and  no  new  model  been  read  in.  Please  read  Section  5. 1.1.1  and 
note  the  changes  in  the  display  possible  through  the  FLATTEN  and  TRIANGLES  buttons. 

For  this  example,  tutorial.gb  is  a  2-D  model  created  in  an  earlier  session  of  Xgbm . 
If  the  user-defined  model  one  wished  to  input  had  been  a  1-D  model  in  ASCII  format,  the 
Xgbm  Model  Choice  would  have  appeared  in  response  to  selecting  the  OK  button.  The 
depth,  breadth,  and  resolution  of  the  2-D  extension  of  the  1-D  model  are  then  set  as 
described  in  Section  5. 1.1.1.  In  this  instance,  the  Regional  and  Global  model  lists  are  ren¬ 
dered  insensitive  to  ensure  that  only  the  user-defined  model  parameters  will  be  set. 

5.1.2  Model  editing 

A  velocity  model  may  be  changed  either  by  repositioning  the  knoipoints  in  space  and 
thereby  altering  the  velocity  gradient  between  knotpoints  or  by  altering  the  velocity  and 
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density  at  a  knotpoint.  Resolution  may  be  increased  in  key  areas  by  adding  knotpoints. 
The  velocity  model  will  not  change  however  until  the  velocity  is  changed  at  the  new  knot- 
points  or  they  are  moved.  That  is,  the  velocity  and  density  at  an  added  knotpoint  is  com¬ 
puted  from  that  knotpoint’ s  neighbors. 

In  order  to  do  any  model  editing  and  for  the  MOVE  KNOTS  and  ADD  KNOTS  but¬ 
tons  to  be  sensitive,  the  TRIANGLE  toggle  button  in  the  VIEW  pulldown  must  be  on  i.e., 
the  triangles  must  be  visible.  (While  this  is  not  strictly  true,  you  can  try  it  the  other  way 
and  observe  the  peculiar  behavior  of  the  display,  it  is  best  for  visual  management  of  the 
changes.)  In  order  to  have  a  common  display  as  a  starting  point,  please  read  in  the 
tutorial.gb  model  as  in  Section  5. 1.1. 2.  The  model  should  be  in  flattened  mode  and  with 
the  triangles  visible. 

One  other  function  that  is  generally  useful  is  the  capability  to  zoom  in  the  display  on 
a  part  of  the  model  that  is  of  interest.  Place  the  pointer  at  the  border  of  the  area  on  which 
you  wish  to  zoom.  Depress  and  hold  down  the  middle  mouse  button,  dragging  the  pointer 
across  the  area  of  interest.  As  long  as  you  hold  down  the  mouse  button,  a  rectangle  will 
be  displayed  with  one  comer  at  the  starting  point  and  the  comer  diagonally  opposite  at  the 
current  pointer  position.  Drag  the  mouse  so  that  the  rectangle  encloses  the  area  of 
interest,  and  then  release  the  middle  mouse  button.  The  display  should  zoom.  To  return 
to  the  previous  display,  be  certain  the  pointer  is  still  in  the  window,  and  click  the  middle 
mouse  button  once. 

5.12.1  Moving  a  knotpoint 

Select  the  EDIT  pulldown  in  the  main  menu  bar.  Toggle  the  MOVE  KNOTS  toggle 
button  from  that  pulldown  to  the  'on'  position.  It  should  appear  highlighted  if  'on' .  Posi¬ 
tion  the  pointer  near  a  knotpoint  that  is  on  the  interior  of  the  model.  Points  on  the  boun¬ 
dary  other  than  the  surface  cannot  be  moved  in  this  version  of  Xgbm .  Perform  a  CtrNeft 
drag.  The  knotpoint  should  move  as  you  drag  the  mouse,  and  the  triangles  sides  attached 
to  that  knotpoint  should  turn  red  as  the  point  is  dragged.  There  is  a  limit  to  how  far  the 
knotpoint  may  be  dragged,  since  triangle  sides  may  not  cross.  If  one  tries  to  drag  the 
knotpoint  too  far,  the  knotpoint  simply  ceases  to  move.  This  may  be  repeated  indefinitely. 
When  the  MOVE  KNOTS  toggle  is  turned  off,  then  it  becomes  again  impossible  to  move 
the  knotpoints. 

5. 1.2. 2  Changing  parameters  of  a  single  knotpoint  or  triangle 

Move  the  pointer  into  the  window  in  which  the  model  is  displayed  and  strike  the  'c' 
key.  A  set  of  crosshairs  should  appear  in  the  window.  Position  the  crosshairs  close  to  the 
knotpoint  whose  velocity  or  density  you  wish  to  change  by  holding  down  the  left  mouse 
button  and  dragging  it  across  the  model  display.  Release  the  mouse  button  when  the 
crosshairs  are  aligned  with  your  target.  Select  the  PARAMETERS  button  of  the  EDIT 
pulldown.  A  popup  entitled  "changeVel"  should  appear: 
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Nearest  Knot  Velocities  and  Density 
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Triangle  Attenuation 
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Nearest  Side  Discontinuity  Order 
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As  you  reposition  the  crosshairs  about  the  screen,  the  text  widgets  in  the  popup  will  be 
updated  accordingly.  To  alter  the  properties  of  the  nearest  knotpoint  or  the  attenuation 
values  of  the  triangle  under  the  crosshairs,  edit  the  appropriate  text  widget.  When  satisfied 
with  the  values,  select  the  SET  button  at  the  lower  left,  and  the  model  will  be  updated. 

5.12.3  Adding  knotpoints 

Toggle  the  ADD  KNOTS  button  in  the  EDIT  pulldown  to  the  ’on’  setting.  Reposi¬ 
tion  the  pointer  within  the  interior  of  the  model  where  you  wish  to  add  a  knotpoint  and 
then  strike  the  ’a’  key.  A  new  knotpoint  will  be  added  at  the  crosshairs,  and  new  sides 
will  form  making  three  triangles  from  what  was  once  one. 

5.12.4  Creating  discontinuities  and  changing  sets 

Select  the  MODEL  button  in  the  EDIT  pulldown.  A  popup  entitled  "Edit  Model" 
will  appear: 
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and  you  will  find  that  the  right  mouse  button  has  been  activated  (but  don’t  test  it  just  yet). 
If  you  are  not  in  flattened  display  mode,  the  program  should  complain  -  this  feature  is 
designed  only  to  work  when  the  model  is  flattened.  So  if  you  didn’t  happen  to  be  in 
flattened  mode,  toggle  the  FLATTEN  button  in  the  VIEW  menu  to  ’on’  and  try  selecting 
the  MODEL  button  again. 

Move  the  pointer  to  where  you  would  like  to  begin  to  add  a  string  of  knotpoints  or 
perhaps  form  a  discontinuity,  then  click  and  drag  the  right  mouse  button.  A  "rubber  band" 
will  stretch  from  where  you  started  to  wherever  you  now  drag  the  pointer.  When  you 
release  the  mouse  button,  the  line  segment  is  frozen  at  that  position.  You  may  add  other 
line  segments  by  repositioning  the  pointer  and  single  clicking  the  right  mouse  button.  If 
you  wish  to  enclose  the  region,  select  the  CLOSE  BUTTON,  and  a  segment  will  be  drawn 
from  the  last  point  to  the  beginning  point.  If  you  make  an  error  and  wish  to  begin  again, 
simply  select  the  CLEAR  button.  This  will  function  until  you  go  to  the  next  step  involv¬ 
ing  the  ADD  DISCON  and  ADD  KNOTS  buttons. 

There  are  now  three  possibilities  for  proceeding.  (1)  If  you  have  closed  the  polygon 
and  wish  to  change  the  properties  of  all  knots  and  triangles  within  the  enclosed  region  but 
do  not  wish  to  add  knots  or  discontinuities,  go  now  to  the  top  of  the  "Edit  Model"  popup 
where  there  are  a  set  of  five  text  widgets  for  v^,  v^,  p,  and  Q^,  and  three  pushbut¬ 
tons,  SET,  ADD  and  MULTIPLY.  You  can  alter  the  values  of  current  selected  knots  and 
triangles  in  the  three  ways  suggested  by  the  buttons.  To  set  the  absolute  value  of  the 
parameters,  enter  those  new  values  in  the  text  widgets,  and  select  SET.  To  increment 
them  by  a  certain  amount,  enter  that  amount  and  select  ADD.  To  apply  a  scale  factor, 
enter  that  factor  and  select  MULTIPLY.  If  the  text  widget  is  left  blank,  that  value  will 
not  be  altered. 

(2)  If  you  wish  what  you  have  drawn  to  be  a  simple,  second  order  discontinuity  in 
velocity  (i.e.,  continuous  velocity  but  discontinuous  first  derivative)  hit  the  ADD  KNOTS 
button,  and  the  model  will  reform  either  by  moving  knots  onto  the  new  segments  if  they 
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are  very  close  or  by  creating  new  knots.  The  program  ignores  values  in  the  parameter  text 
widgets  at  the  top.  Values  for  ,  v^,  p,  and  Gp  are  derived  by  linear  interpolation  or 
direct  transfer  from  the  parent  knots  and  triangles. 

(3)  If  you  wish  to  create  the  usual  kind  of  discontinuity  (in  both  velocity  and  its 
derivative),  choose  ADD  DISCON,  and  the  model  will  be  reformed  in  a  fashion  similar  to 
the  ADD  KNOTS  response.  However,  this  time  co-located  knots  are  created  to  form  the 
discontinuity.  Unhappily,  since  the  parameters  of  these  knotpoints  are  also  set  by  linear 
interpolation,  the  co-Iocated  points  have  die  same  values,  i.e.,  the  velocity  does  not 
increase  discontinuously. 

To  resolve  this  inconsistency,  the  velocities  and  densities  on  one  side  of  the  discon¬ 
tinuity  may  be  changed  one  knotpoint  at  a  time  as  described  in  Section  5. 1.2.2  or  by 
selecting  all  triangles  within  the  new  discontinuity.  This  later  process  will  now  be 
described.  Try  to  form  an  enclosed  discontinuity  as  a  trial. 

One  can  change  all  the  properties  of  the  interior  of  that  new  discontinuity  by  moving 
the  pointer  into  the  interior  and  striking  the  letter  's'.  It  should  change  background  color. 
Now  go  to  the  top  of  the  "Edit  Model"  popup  where  there  are  a  set  of  five  text  widgets 
for  Vp,Vg,  p,  Qg.,  and  Q^,  and  three  pushbuttons,  SET,  ADD  and  MULTIPLY.  As  in  (1) 
above,  you  can  alter  the  values  of  cuirent  selected  knots  and  triangles  in  the  three  ways 
suggested  by  the  buttons.  To  set  the  absolute  value  of  the  parameters,  enter  those  new 
values  in  the  text  widgets,  and  select  SET.  To  increment  them  by  a  certain  amount,  enter 
that  amount  and  select  ADD.  To  apply  a  scale  factor,  enter  that  factor  and  select  MULTI¬ 
PLY.  If  the  text  widget  is  left  blank,  that  value  will  not  be  altered. 

5.1.3  Model  output 

Once  velocity  model  editing  is  complete,  one  may  store  the  altered  model  for  future 
use  by  selecting  the  SAVE  button  in  the  FILE  pulldown  of  the  main  meun  bar.  A  popup 
entitled  "Xgbm  OutfilePrompt"  should  appear.  If  the  default  string  in  the  text  widget  is 
not  what  you  wish  to  use  for  your  output  file  name,  delete  it  by  moving  the  pointer  into 
the  text  widget,  double  clicking  on  the  text  (it  should  change  to  reverse  video),  and  strik¬ 
ing  the  delete  key.  The  string  should  disappear.  Enter  the  output  file  name  you  wish  to 
use  and  append  a  .gb  suffix.  Select  the  OK  button  at  the  bottom.  The  model  will  be 
preserved  in  the  directory  pointed  to  by  the  GBWORKENV  environment  variable.  (See 
Section  4.)  To  recover  this  model,  see  Section  5. 1.1.2. 

5.2  Source/Receiver  Manipulation 

It  is  possible  to  add,  delete,  and  reposition  sources  and  receivers  in  several  ways: 

5.2.1  Adding/deleting  sources 

Select  the  VIEW  pulldown  from  the  main  menu  and  then  select  SOURCE.  A  further 
pulldown  menu  with  the  buttons  ADD,  DELETE,  DELETE  ALL,  and  LOCK  should 
appear.  To  add  a  source,  select  ADD.  A  small  star  should  appear  at  the  X=0.0  coordi¬ 
nate  at  a  depth  that  will  depend  on  the  maximum  depth  of  your  model.  You  may  add 
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more  than  one  source,  but  rays  will  be  traced  only  from  the  most  recently  added  or  relo¬ 
cated  source.  Selecting  DELETE  will  delete  the  most  recently  added  source.  Selecting 
DELETE  ALL  will  delete  all  sources. 

5.2.2  Adding/deleting  receivers 

Select  the  VIEW  pulldown  from  the  main  menu  and  then  select  RECEIVER.  A 
further  pulldown  menu  with  the  buttons  ADD,  ADD  STRING,  DELETE  and  DELETE 
ALL  should  appear.  To  add  a  single  receiver,  select  the  ADD  button.  A  small  filled  tri¬ 
angle  should  appear  at  the  free  surface.  To  delete  one  or  more  receivers,  select  DELETE 
or  DELETE  ALL,  respectively.  To  place  a  string  of  receivers,  select  the  ADD  STRING 
button.  A  popup  entitled  "Receiver  String"  should  appear.  In  this  popup  are  three  text 
widgets  labeled  from  top  to  bottom  Min  distance.  Spacing,  and  Num  receivers.  Each  may 
be  edited.  The  units  and  the  frame  of  reference  for  the  first  two  depend  upon  the  state  of 
the  KM  and  RELATIVE  toggles  of  the  "coordinates"  popup.  See  Section  5.2.3  for  more 
information.  When  you  select  the  APPLY  button,  the  popup  will  disappear  and  the 
receivers  will  be  added. 

5.2.3  Repositioning  sources  and  receivers 

The  simplest  way  to  move  a  source  or  receiver  is  to  position  the  pointer  near,  depress 
the  left  mouse  button  and  drag  the  symbol  to  the  desired  location.  Care  must  be  taken, 
because  the  symbol  to  be  moved,  source  or  receiver,  will  be  the  one  closest  to  the  pointer. 
It  is  therefore  possible  to  move  a  receiver  when  one  really  wishes  to  move  the  source,  or 
vice  versa,  unless  one  uses  adequate  caution.  It  is  possible  to  move  the  source  beyond  the 
model  boundaries,  but  if  left  there,  no  rays  may  be  traced  from  it.  In  either  display  mode, 
receiver  symbols  are  constrained  to  move  along  the  firee  surface  only.  In  earlier  versions 
when  in  "spherical"  display  mode,  receivers  could  be  dragged  anywhere,  but  when  the 
mouse  button  was  released,  they  would  "snap"  to  the  nearest  point  on  the  free  surface. 

There  are  many  times  when  greater  precision  is  required.  Select  the  COORDS  button 
in  the  VIEW  pulldown.  A  popup  entitled  "coordinates"  should  appear.  Now  reposition  a 
source  or  receiver  as  described  in  the  preceding  paragraph  and  watch  as  the  text  widgets 
of  the  popup  are  updated.  (If  you  have  no  source  or  no  receiver,  that  widget  should  be 
blank.)  The  coordinates  displayed  are  for  the  source  or  receiver  most  recently  added  or 
moved. 

There  are  two  toggle  buttons  called  KM  and  RELATIVE  at  the  bottom  of  the  popup. 
When  ’on’  (  default  )  KM  means  the  receiver  coordinates  will  be  expressed  in  km,  when 
’off’,  in  degrees.  The  frame  of  reference  for  the  receiver  positions  is  set  by  the  RELA¬ 
TIVE  toggle.  When  ’off  (  default  ),  the  frame  of  reference  is  relative  to  the  model  coor¬ 
dinate  origin.  When  ’on’  the  frame  of  reference  is  relative  to  the  source’s  current  horizon¬ 
tal  coordinate.  To  position  a  source  or  receiver  at  a  precise  spot,  edit  the  source  depth 
and  receiver  position  text  widgets,  and  then  select  the  SET  button  at  the  bottom.  The 
position  of  the  most  recently  added  source  and  receiver  will  be  updated  accordingly. 
Note,  therefore,  i.iat  if  you  wish  to  place  precisely  more  than  one  receiver,  it  is  necessary 
to  add  one  at  at  time,  using  the  SET  button  to  place  each  one  immediately  after  it  is 
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added. 

5.2.4  Using  geotool  to  positioning  source  and  receivers 

[Isis  or  ipcc  IPC  mode  only!]  It  is  possible  to  construct  a  display  which  accurately 
reflects  (as  far  as  is  possible  in  2-D)  the  source-receiver  geometry  of  the  data  you  are 
reviewing.  For  this  function  to  work  properly,  one  must  be  running  geotool  and  Xgbm  in 
an  IPC  mode,  geotool  must  have  origin  infomiation  (i.e.,  it  must  have  an  origin  file)  for 
the  data,  and  Xgbm  must  be  currentiy  displaying  a  velocity  model  wide  enough  to  accom¬ 
modate  the  maximum  source-receiver  separation.  First  examine  the  waveform  data  you 
wish  to  model  using  geotool.  Select  those  traces  you  wish  to  model,  and  then  bring  up 
limit  lines  by  striking  the  7’  key.  Position  the  limit  lines  to  bracket  the  time  segment  you 
wish  to  model.  Now  direct  your  attention  back  to  Xgbm.  Select  the  OPTIONS  button  in 
the  main  menu  bar,  followed  by  QUERY  GEOTOOL.  The  following  should  happen:  (1) 
Xgbm  deletes  sources  and  receivers  in  the  display,  (2)  Xgbm  sends  an  IPC  query  (Selec- 
tedWaveforms  in  Appendix  A)  to  geotool  asking  for  the  source-receiver  location  informa¬ 
tion,  (3)  geotool  sends  Xgbm  a  reply  (also  called  SelectedWaveforms),  (4)  Xgbm  plots  a 
source  at  the  x=0,  z=source  depth  coordinates,  and  (5)  Xgbm  plots  receiver  symbols  at 
distances  corresponding  to  geotool's  IPC  reply.  Note  that  all  azimuthal  information  is  lost 
—  receivers  located  at  azimuths  diametrically  opposite  the  source  may  in  fact  plot  very 
close  to  one  another  in  the  Xgbm  display.. 

5.3  Phase  Selection 

Once  a  velocity  model  is  read  in  and  modified  as  necessary,  and  once  a  source  is 
placed,  the  user  is  ready  to  perform  raytracing.  To  do  so  it  is  necessary  to  select  the 
phases  to  be  traced.  These  f^all  into  three  categories:  phases  with  conventional  names 
which  appear  in  Xgbm’s  default  list,  phases  with  conventional  names  which  are  not  in 
Xgbm’s  default  list,  and  phases  for  which  there  is  no  convention.  For  the  following 
tutorial,  it  would  be  useful  to  read  in  a  jb  velocity  model  extending  down  to  include  the 
inner  core  with  a  full  360°  breadth.  Place  a  source  in  the  mantle. 

5.3.1  Standard  phases  in  list 

Select  OPTIONS  followed  by  PHASE  LIST.  A  popup  entitled  "Pha:;e  List"  should 
appear: 
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At  the  top  of  this  popup  is  a  scrollable  list  with  a  large  number  of  entries  in  it.  Each 
entry  consists  of  a  common  phase  name  followed  by  three  numbers.  Look  at  the  first  ele¬ 
ment  of  the  list:  "P  0.0  90.0  10".  This  is  to  indicate  that  ten  rays  of  the  phase  P  are  to  be 
traced  from  a  takeoff  angle  of  0°  (straight  down)  to  90°  (counter-clockwise).  Select  this 
item  now,  and  then  select  the  APPLY  button  at  the  extreme  lower  left  of  the  popup.  A 
number  of  rays,  blue  in  color  if  you  have  a  color  display,  should  be  plotted  outward  from 
the  source.  Careful  inspection  will  show  that  they  do  not  number  ten,  as  expected  from 
the  list  item.  Xgbm  will  not  plot  rays  which  do  not  fit  its  ray  description.  Consider  the  P 
ray  which  begem  at  takeoff  angle  0°.  The  ray  is  traced  directly  downward  until  it 
encounters  a  discontinuity,  the  core-mantle  boundary  in  this  case.  Because  it  is  named  P 
and  not  PcP  or  PKP ,  tracing  ceases  at  this  point  and  no  segment  of  the  ray  is  plotted. 
Try  a  few  other  examples.  You  can  plot  more  than  one  ray  type  by  holding  down  the 
Control  key  as  you  make  your  picks.  Do  not  forget  to  select  APPLY  to  plot  the  rays. 
Note  the  5  rays  segments  are  plotted  in  red. 

It  is  frequently  essential  to  edit  the  takeoff  angles  and  number  of  rays  to  be  plotted 
for  each  phase.  Select  and  plot  PKP  at  a  source  depth  of  100  km  for  example.  There  is 
only  one  ray  plotted  for  the  entry  "PKP  0.0  90.0  10".  Direct  your  attention  to  the  central 
portion  of  the  "Phase  List"  popup  where  there  are  located  three  text  widgets  labeled  Min 
Tdceoff  Angle,  Max  Takeoff  Angle,  and  Number  of  rays.  Edit  these  values  to  5.0,  30.0  and 
20,  respectively.  As  you  change  each  text  entry,  all  selected  items  in  the  list  (in  this  case 
the  PKP  entry  only)  will  now  change  to  reflect  the  text  widgets’  current  values.  'iTie  rays 
will  not  be  retraced  until  you  select  the  APPLY  button  below  or  until  you  move  the 
source.  Select  APPLY  now  and  observe  that  many  more  rays  are  plotted  and  both  the  AB 

-  20  - 


Version  1.1 


and  BC  branches  of  PKP  are  traced. 

There  is  yet  another  useful  feature  in  this  popup  which  can  now  be  illustrated.  Add  a 
receiver  and  position  it  at  a  distance  so  that  at  least  one  PKP  ray  terminates  on  either  side 
of  that  receiver.  Then  select  the  AUTO  button  in  the  second  row  from  the  bottom.  This 
initiates  a  primitive  search  routine  to  refine  the  takeoff  angles,  traces  new  rays  based  on 
the  solution  found  by  the  routine,  and  updates  the  list  entry.  This  will  work  for  multiple 
phases  provided  each  phase  has  rays  which  bracket  the  receiver.  Further,  if  more  than  one 
receiver  is  displayed,  the  initial  rays  given  the  routine  must  bracket  the  distance  spanned 
by  the  nearest  and  furthest  receivers. 

5.32  Standard  phases  not  in  list 

Select  OPTIONS  followed  by  PHASE  LIST  as  in  Section  5.3.1.  In  the  "Phase  List" 
popup  which  appears,  direct  your  attention  to  the  third  row  from  the  bottom  where  a  text 
widget  labeled  Phase  Code  to  the  right  of  which  a  pushbutton  ADD  are  located.  Enter 
PPP  in  the  text  widget,  and  select  ADD.  The  entry  "PPP  0.0  90.0  10”  should  be  added  to 
the  top  of  the  list  of  phases.  Select  the  PPP  item  now  and  then  hit  APPLY  at  the  extreme 
lower  left.  A  number  of  PPP  rays  should  now  be  displayed.  See  Section  5.3.1  for  many 
details  of  how  to  change  the  takeoff  angles  and  number  of  rays. 

5.3.3  Non-standard  phases 

For  many  models,  especially  those  with  many  discontinuities  and  those  in  2-D  and 
3-D,  it  is  difficult  to  plot  a  number  of  phases  that  are  nevertheless  of  considerable  impor¬ 
tance  to  research  and  analysis.  Xgbm  gives  the  user  the  capability  to  create  these  phases, 
name  them,  and  then  preserve  them  for  future  use.  First,  bring  up  the  "Phase  List"  popup 
as  explained  in  Section  5.3.1.  Now  select  EDIT  from  the  main  menu  bar,  followed  by 
MAKE  PHASE.  A  popup  entitled  "Make  Phase"  should  appear: 
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It  consists  of  two  text  widgets  labeled  Phase  Name  and  Takeoff  Angle  at  the  top,  a  row  of 
two  toggle  buttons  labeled  P,  S,  below  them,  and  a  row  of  four  pushbottons,  BEGIN, 
TRANSMIT,  REFLECT,  and  END  below  them.  To  create  a  ray,  it  is  necessary  for  the 
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user  to  give  Xgbm  a  paradigm  for  it  to  duplicate.  That  is,  one  must  trace  a  ray  through 
the  model,  specifying  a  ray  type  for  each  segment  (defined  as  that  portion  of  a  trajectory 
between  discontinuities)  until  that  ray  terminates  at  the  free  surface.  As  an  example,  first 
position  your  source  just  below  the  free  surface.  Now  give  the  phase  a  name  (limit  this  to 
less  than  32  characters,  please)  and  an  initial  takeoff  angle  by  putting  entries  in  the  text 
widgets.  A  good  illustration  is  to  use  a  takeoff  angle  of  5°  or  10°.  Now  choose  whether 
the  ray  is  to  begin  as  a  P  wave  or  an  S  wave  by  selecting  the  appropriate  toggle  button. 
These  two  buttons  function  as  radio  buttons,  i.e.,  their  selection  is  mutually  exclusive. 
Now  hit  BEGIN.  The  program  should  plot  a  ray  segment  that  extends  from  the  source 
symbol  down  to  the  first  discontinuity  below  the  source,  probably  the  15  km  deep  Conrad 
discontinuity  if  you  are  using  the  jb  model  and  have  placed  your  source  at  depth  less  than 
15  km.  You  must  now  decide  where  you  wimt  the  phase  to  travel.  Try  selecting 
REFLECT.  Xgbm  should  plot  a  second  segment  that  goes  up  to  the  next  discontinuity, 
the  free  surface.  Had  you  hit  TRANSMIT  instead,  the  ray  should  have  traveled  to  the 
Moho  and  stopped  to  wait  for  user  instructions.  Tiy  a  number  of  possibilities  for 
reflection/transmission  and  ray  type.  If  you  make  a  mistake,  simply  reset  your  initial  set¬ 
ting  and  hit  BEGIN  again.  When  you  are  finished,  select  END.  As  long  as  the  ray  ter¬ 
minates  at  the  free  surface  (Xgbm  will  complain  otherwise),  the  phase  you  have  named 
will  be  prepended  to  the  phase  list  in  the  "Phase  List"  popup.  You  may  manipulate  the 
new  phase  using  "Phase  List"  just  as  you  would  the  conventional  phases  in  the  list. 

You  may  retain  the  phases  you  have  created  and  any  takeoff  angles  you  have 
adjusted  for  conventional  phases  by  selecting  the  SAVE  button  in  the  "Phase  List"  popup. 
A  popup  labeled  "Save  Selected  Phases"  will  appear.  Enter  a  filename  in  which  you  wish 
to  save  the  list,  and  hit  APPLY.  The  list  will  be  saved  in  that  file.  To  recover  the  list, 
select  INPUT  in  the  "Phase  List"  popup.  A  popup  labeled  "Input  User-Defined  Phases" 
will  appear.  Enter  the  filename  of  the  file  in  which  you  have  saved  your  phases  in  the 
text  widget  and  hit  APPLY.  The  phase  list  will  be  updated  accordingly.  Please  remember 
that  these  phase  definitions  are  tied  to  a  specific  velocity  model  that,  in  principal,  may 
deviate  very  much  from  a  laterally  homogeneous  model.  Xgbm  makes  no  check  for  user 
error. 

It  is  possible  to  view  the  traveltime  curves  for  selected  phases.  Select  OPTIONS  fol¬ 
lowed  by  TRAVEL  TIME  CURVES.  Be  sure  you  have  one  or  more  phases  selected  in 
the  phase  list.  Now  select  the  APPLY  button  in  the  "Phase  List"  popup.  Traveltime 
curves  should  appear  on  the  display.  Now  change  the  source  depth.  A  second  set  of 
curves  should  be  superimposed  on  the  display.  To  prevent  superposition,  toggle  the 
AUTO  CLEAR  button  to  ‘on’.  Then  each  time  the  source  is  moved  or  the  APPLY  button 
is  selected,  the  traveltime  display  will  be  cleared  before  the  new  curve  or  curves  are  plot¬ 
ted. 

5.4  Seismogram  Computation 

Once  raytracing  has  been  performed,  there  is  one  critical  action  required  of  the  user 
before  seismograms  may  be  computed:  the  raytracing  results  must  be  stored  to  a  disk  file. 
This  is  controlled  by  a  toggle  button  in  the  FILE  pulldown  called  WRITE.  When  this  tog¬ 
gle  is  ’on’,  the  raytracing  results  are  written  to  a  file  named  by  default  rays. out  in  the 
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GBWORKENV  directory.  (How  to  use  another  name  is  explained  below.)  The  default 
position  of  the  WRITE  toggle  is  ’on’  so  that  novice  users  will  not  lose  their  raytracing 
results  by  mistake  or  worse,  use  results  from  an  earlier  worksession.  Xgbm  will  run  a  bit 
faster  with  WRITE  in  the  ’off  position  however.  The  user  can  experiment  with  which 
rays  to  include  and  their  number  and  takeoff  angles,  then  toggle  the  WRITE  button  back 
to  the  ’on’  position  and  all  rays  currently  traced  will  be  written  to  disk.  While  ’on’ ,  any 
alteration  in  the  source  position  or  hitting  the  APPLY  button  in  the  "Phase  List"  popup 
will  cause  the  ray  output  file  to  be  re-written.  Therefore  if  one  wishes  to  retain  the  ray¬ 
tracing  results  for  a  particular  model,  source  position  and  phase  selection,  it  is  prudent  to 
select  a  unique  name  for  the  output  file  and  to  change  that  name  before  altering  any  of  the 
above.  The  WRITE  toggle  has  occasioned  considerable  confusion  among  users  of  the  beta 
release  of  Xgbm ,  but  has  been  retained  for  flexibility. 

The  raytracing  output  file  contains  information  about  the  source  position  and  the  ray¬ 
tracing  results,  but  nothing  about  the  receiver  location(s).  GBseis  can  access  this  file  and 
use  it  to  respond  to  queries  for  phase  traveltime.  However,  in  order  to  use  Xgbm  as  a 
preprocessor  for  GBseis  to  compute  a  synthetic  seismogram,  it  is  first  necessary  to  have  at 
least  one  receiver  in  the  display.  Before  continuing  with  this  portion  of  the  tutorial,  check 
to  be  sure  you  have  at  least  one  receiver  visible,  and  if  not,  add  one.  (See  Section  5.2.2.) 

Now  select  OPTIONS  followed  by  COMPUTE  SEISMOGRAM.  A  popup  entitled 
"Xgbm  Seismogram  Computation"  should  appear: 


This  button  is  used  by  Xgbm  to  construct  a  message  to  GBseis  telling  GBseis  how  to 
compute  the  seismogram.  If  Xgbm  is  running  in  an  IPC  mode,  either  with  IS/S  or  with 
ipcc ,  this  information  will  be  pa.ssed  by  IPC  message.  (See  Appendix  A  -  Dogbseis.) 
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Otherwise,  Xgbm  creates  a  small  file  and  spawns  an  instance  of  GBseis  to  carry  it  out. 
All  of  this  is  invoked  by  selecting  the  APPLY  button  in  the  lower  left. 

But  first,  it  may  be  necessary  to  adjust  the  parameters.  Every  button  above  the 
second  row  from  the  bottom  controls  parameters  effecting  seismogram  computation. 
OPTION  at  the  top  left  is  how  one  choose  from  the  nine  possibilities  Weber  (1988a) 
offers  for  computing  the  Gaussian  beam  parameter  e.  The  reader  is  referred  to  Weber’s 
paper  especially  pages  13-15  for  a  fuller  explanation  of  their  meaning.  Option  9  is  the 
default.  If  options  1-3  or  6  are  selected,  values  for  e|,  £2  and  the  beamwidth  are  soli¬ 
cited  via  popups. 

XgbmIGBseis  can  compute  seismograms  with  or  without  the  effects  of  Q.  The 
default  is  the  anelastic  case.  To  ignore  absorption  and  dissipation,  select  the  button  ANE- 
LASTIC  and  two  buttons  will  appear  —  ANELASTIC  and  ELASTIC.  Release  the  mouse 
button  on  ELASTIC.  To  go  back,  reverse  the  procedure. 

Sometimes  when  using  very  broad  Gaussian  beams,  it  is  necessary  to  use  slowness 
tapers  to  reduce  numerical  instability.  These  are  invoked  by  selecting  SLOWNESS 
TAPER.  A  popup  entitled  "qtaper"  should  appear  with  four  text  widgets  labeled  ql-q4, 
one  toggle  button  ACTIVATE,  and  two  pushbuttons,  HIDE  and  HELP.  The  taper  is  a 
cosine  taper  with  one  limb  between  ql  and  q2  and  a  second  between  q3  and  q4.  The 
ACTIVATE  toggle  controls  input  to  the  text  widgets  and  whether  this  information  is  used 
by  Xgbm  or  not.  In  the  default  ’ojf  position,  one  cannot  enter  or  edit  what  is  in  the  ql- 
q4  text  widgets,  and  Xgbm  will  ignore  this  information  when  composing  its  message  to 
GBseis .  In  the  ’on'  position,  text  may  be  entered  and  will  be  used  in  the  computation. 

The  slider  labeled  Effective  beamwidths  allows  the  user  to  override  a  default.  Nor¬ 
mally,  GBseis  will  only  sum  beams  which  terminate  within  two  effective  beamwidths  of 
the  receiver.  (See  Weber,  1988a.)  By  placing  the  pointer  over  the  slider  and  depressing 
the  left  mouse  button,  this  may  be  adjusted  at  between  1-5. 

The  radio  buttons  in  the  partition  called  "Source-Time  Function"  allow  the  user  to 
control  the  shape  and  duration  of  the  source  wavelet.  Selecting  either  KUEPPER  SIG¬ 
NAL  or  USER-DEFINED  will  cause  a  popup  entitled  "Kuepper  signal"  or  "Xgbm  Src- 
Time  Funct  Input",  respectively,  to  appear.  Which  one  Xgbm  uses  is  governed  by  which 
radio  button  is  currently  on.  The  shape  of  the  Kuepper  signal  wavelet  {Kupper,  1958)  is 
set  by  specifying  its  period  T  (duration  in  the  popup)  and  an  integer  n  (shape  in  the 
popup): 

fit)  =  sini  nn-^) - ^sini  (n+2)  Tt  -jr),  0<t<T 

T  n +2  T 

Simply  put,  /i=l  is  a  one-sided  wavelet,  n=2  is  two-sided,  etc. 

In  order  to  give  the  user  greater  flexibility,  the  USER-DEFINED  button  was 
included.  The  user  first  creates  a  file  in  which  a  time  series  of  arbitrary  complexity  is 
written  in  ASCII  free  format.  The  name  of  this  file  is  input  into  the  text  widget  of  the 
"Xgbm  Src-Time  Funct  Input"  popup  and  will  be  registered  with  Xgbm  when  the 
ACCEPT  button  of  that  popup  is  selected.  That  file  will  not  be  read,  however,  until 
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GBseis  is  ordered  by  Xgbm  to  use  it.  This  will  happen  only  if  the  USER-DEFINED  tog¬ 
gle  is  on  when  APPLY  of  "Xgbm  Seismogram  Computation"  is  selected.  Xgbm  sets  the 
sampling  interval  for  this  source  wavelet  from  the  data  it  is  currently  modeling  or  from  the 
"Seismogram  length"  popup.  (See  below.) 

Source  type  may  be  set  via  the  type  pulldown.  Click  on  the  EXPLOSION  button  and 
a  cascade  will  appear  with  buttons  for  each  possible  source  type:  EXPLOSION,  LINE 
SOURCE,  and  DOUBLE  COUPLE.  Releasing  the  button  on  any  sets  that  type.  As 
DOUBLE  COUPLE  is  selected,  a  popup  entitled  "Xgbm  Focal  Mechanism"  will  appear. 
This  popup  contains  four  sliders,  one  for  each  parameter  in  a  focal  mechanism.  The  con¬ 
vention  utilized  is  that  of  Aki  and  Richards  (1980),  pp.  105-115.  Normally  azimuth 
defaults  to  zero.  If  an  IPC  message  has  been  exchanged  with  geotool,  that  value  is 
updated  to  reflect  the  azimuth  of  the  station  first  selected  in  the  geotool  display.  These 
values  will  be  used  only  if  the  DOUBLE  COUPLE  button  is  selected  when  APPLY  is  hit. 

The  user  may  wish  to  control  the  beginning  time  Tq  (relative  to  origin  time),  sam¬ 
pling  interval  dt,  and  duration  npts*dt,  of  the  time  series  to  be  calculated.  Xgbm  nor¬ 
mally  establishes  the  following  priorities  to  determine  these  values:  (1)  If  the  user  is 
currently  modeling  data  based  upon  a  query  to  geotool,  this  information  is  derived  from 
the  IPC  message  (SelectedWaveforms)  in  reply.  (2)  Xgbm  examines  all  rays  terminating 
within  the  number  of  effective  beamwidths  set  by  that  slider  and  computes  the  minimum 
and  maximum  traveltime  from  this  group  to  the  current  receivers.  To  is  set  to  10%  less 
than  the  minimum  traveltime,  dt  is  set  to  the  Kuepper  signal  duration  divided  by  twenty. 
Duration  is  set  to  20%  longer  than  the  difference  between  minimum  and  maximum  travel- 
time.  (3)  Tq  =  0,  dt=0.1  sec,  and  duration  is  set  to  dt/1024.  This  may  be  overridden  by 
selecting  the  SET  LENGTH  button.  A  popup  entitled  "Seismogram  Length"  will  appear 
with  three  text  widgets  labeled  Npts,  dt,  and  TO.  There  is  a  toggle  button  ACTIVATE  at 
the  bottom.  When  ACTIVATE  is  in  the  default  ’off  position,  the  text  widgets  cannot  be 
edited  and  Xgbm  will  ignore  their  values  in  constructing  its  message  to  GBseis.  When 
'on',  the  widgets  are  editable  and  will  be  used  to  override. 

The  RAYFILE  NAME  pushbutton  and  its  associated  popup  "Xgbm  Rayfile  Name 
Input"  were  alluded  to  at  the  very  beginning  of  this  section.  The  name  in  the  text  widget 
of  "Xgbm  Rayfile  Name  Input"  is  used  as  the  output  file  name  for  raytracing  output.  It 
may  also  be  used  to  calculate  seismograms  for  raytracing  results  computed  much  earlier 
and  stored.  Merely  enter  the  filename  of  the  earlier  results  in  the  widget,  and  the  next 
time  APPLY  is  hit,  that  file  will  be  accessed  by  GBseis . 

Once  all  the  parameters  have  been  set,  Xgbm  is  ready  to  send  its  instructions  to 
GBseis.  One  more  check  is  in  order,  however.  In  order  for  GBseis  to  calculate  accu¬ 
rately  a  phase’s  contribution  to  a  seismogram,  it  is  necessary  for  a  number  of  rays  (a  good 
rule-of-thumb  is  five)  of  that  phase  type  to  terminate  within  the  critical  effective 
beamwidth  limit,  thereby  giving  an  reasonable  sample  of  the  medium.  The  way  to  check 
how  many  have  actually  done  so  is  to  select  the  CHECK  button  at  the  bottom.  A  popup 
entitled  "Xgbm  Information"  will  appear: 
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For  each  receiver  are  listed  the  number  and  type  of  phases  which  terminate  nearby.  In 
this  example,  there  are  two  receivers,  each  with  one  P  ray  and  no  S  rays  nearby.  One 
should  increase  the  number  of  rays  calculated  or  narrow  the  takeoff  angles  in  order  to 
raise  this  level  to  five  or  greater. 

Select  the  APPLY  button  in  "Xgbm  Seismogram  Computation."  The  status  display 
in  the  second  row  will  change  to  reflect  what  is  happening  that  is  hidden  from  the  user. 
Whether  ’on’  or  ’off  before  APPLY  was  selected,  the  SEISMOGRAM  DONE  button 
should  be  ’off  immediately  afterward.  It  will  blink  ’on’  again  when  GBseis  has  com¬ 
pleted  its  calculation.  If  running  in  either  IPC  mode,  Xgbm  will  immediately  send  an  IPC 
message  (called  vvfdisc_3.0  in  Appendix  A)  to  geotool  to  display  the  newly-calculated 
synthetic  seismogram,  and  the  GEOTOOL  DISPLAY  button  should  blink  ’on’ .  geotool 
should  display  the  calculation  momentarily. 

The  parameters  in  this  popup  can  be  readjusted  at  this  point  and  a  new  seismogram 
computed  immediately.  Only  if  the  source  is  repositioned  or  if  the  velocity  model  is 
changed  is  it  necessary  to  re-write  the  raytracing  output  file  before  continuing.  It  is 
instructive  to  make  successive  calculations,  changing  only  the  Kuepper  signal  duration  or 
switching  from  elastic  to  anelastic  computations. 

The  following  note  applies  to  naming  the  seismogram  output  files.  In  order  to  avoid 
name  conflicts  by  repeated  calculations  in  one  or  more  work  sessions,  Xgbm  constructs 
unique  names  for  the  output  synthetic  seismogram  files  from  its  process  id  number  and  an 
internal  counter.  A  typical  basename  for  output  might  be  syn_2537_3  where  2537  is  the 
process  id  for  the  current  run  of  Xgbm  and  3  indicates  this  is  the  third  seismogram  com¬ 
puted  in  this  session. 

5.5  Color  Display 

The  background  may  be  changed  to  colors  proportional  to  ,  Vj ,  or  p  by  choosing 
the  appropriate  pushbutton  in  the  COLOR  pulldown  of  the  VEW  menu.  The  actual 
colors  used  are  controlled  by  the  file  xgb.rgb  which,  for  this  version  of  Xgbm  must  be 
located  in  the  current  working  directory.  The  file  consists  of  three  columns  of  numbers 
that  represent  intensities  of  red,  green  and  blue.  The  xgb.rgb  file  distributed  with  this 
release  is  not  coded  to  a  particular  velocity  scheme,  so  the  user  will  certainly  wish  to 
change  the  colors  to  assemble  a  satisfying  display. 
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The  number  of  colors  a  woricstation  can  handle  is  hardware  dependent.  Please  con¬ 
sult  your  system  administrator  for  what  that  value  is.  A  similar  file  called  rgb.txt  comes 
with  releases  of  X  and  associates  common  names  with  the  three-color  intensity  codes. 
That  file  is  found  in  the  /usr/lib/Xll  directory. 

5.6  Interfacing  with  GIS 

Users  with  an  Internet  address  may  take  direct  advantage  of  the  capability  to  extract 
topography  and  moho-depth  information  contained  in  databases  to  which  CSS  users  have 
access.  Those  users  who  do  not  have  access  may  still  exploit  this  feature  of  Xgbm  by 
creating  input  files  of  the  format  described  in  Appendix  B.  This  section  of  the  tutorial 
makes  use  of  such  a  file,  GERESS_south.topOy  found  in  the  vmodels  subdirectory,  but  the 
direct  database  connection  will  be  described  as  well. 

Click  first  on  FILE  followed  by  SET  GIS.  The  popup  "GIS  Input"  should  appear; 


Enter  the  string  /voodoo/vmodels/GERESS_south.topo  in  the  Input  Filename  text  widget 
and  then  press  HIDE.  (As  the  name  suggests,  GERESS_south.topo  is  a  representation  of 
structure  to  the  south  of  the  GERESS  array  and  is  shown  also  in  Davis  and  Henson, 
[1993].)  Now  click  on  the  FILE  pulldown  again,  and  this  time,  toggle  the  USE  GIS  but¬ 
ton  to  ’on’ .  Now  choose  FILE  followed  by  INPUT  and  then  STANDARD.  When  the 
"Xgbm  Model  Choice"  popup  appears,  choose  the  Global  jb  model,  and  set  the  depth  to 
60  km,  the  breadth  to  4000  km,  and  the  number  of  knots  to  100.  Hit  APPLY.  Because 
you  have  set  the  USE  GIS  button  to  ’on’ ,  Xgbm  is  forced  to  check  the  "GIS  Input"  popup 
for  topography  data.  Since  you  have  filled  in  the  Input  Filename  widget  of  "Xgbm  Model 
Choice",  Xgbm  will  read  that  string  and  try  to  open  a  file  of  that  name.  The  model  to 
appear  should  look  like: 
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This  rendering  of  the  topographic  data  contained  in  GERESS_south.topo  is  unsatisfactory 
as  a  check  of  the  data  in  the  file  will  reveal.  The  horizontal  lines  on  the  right  side  begin¬ 
ning  at  about  x=2600  km  occur  because  data  for  the  second  and  third  discontinuities  do 
not  extend  along  the  entire  4000  km  section.  At  the  point  in  the  cross-section  where 
depth  values  terminate,  Xgbm  begins  abruptly  to  use  the  original  model  basis  depths,  in 
this  case,  15  km  and  33  km. 

More  problematical  is  that  the  surface  topography  has  been  distorted  by  Xgbm’s 
attempt  to  accommodate  undulations  in  the  second  layer  where  it  is  very  near  the  surface. 
Xgbm  acts  to  prevent  the  aspect  ratio  of  its  constituent  triangles  from  becoming  too 
severe,  and  in  this  case,  the  consequence  is  to  push  the  topography  up  too  far.  That  is,  a 
minimum  thickness  for  the  layer  is  established,  and  where  the  trial  thickness  is  less  than 
that  minimum,  the  surface  is  pushed  upward. 

This  is  a  problem  of  resolution  and  can  be  corrected  by  increasing  the  number  of 
knotpoints.  Click  on  FILE  followed  by  INPUT  and  then  STANDARD.  This  time  change 
the  number  of  knots  to  1000,  and  then  hit  APPLY.  The  new  rendering  should  look  like: 
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This  is  a  much  more  faithful  representation  of  the  database  information. 


Had  the  user  wished  to  obtain  a  different  cross-section,  the  appropriate  action  is  to 
fill  in  the  Source  and  Receiver  Latitude  and  Longitude  of  the  "GIS  Input"  popup.  These 
two  pairs  represent  the  endpoints  of  the  cross-section.  One  may  enter  the  cross-section 
endpoints  or  a  file  name  but  not  both.  If  the  endpoint  coordinates  are  entered  and  the 
USB  GIS  toggle  is  on,  then  when  the  APPLY  button  of  the  Xgbm  Model  Choice”  popup 
is  pushed,  Xgbm  spawns  an  gc_raster  process  which  will  connect  to  a  database  and  write 
a  file  called  Xgbm.gis  which  is  then  read  by  Xgbm .  Just  which  machines  and  databases 
are  contacted  are  specified  as  resources  in  the  X  resource  file  XgbmFirst  as 
Xgbm.gisServers.  The  resource  is  typically  a  series  of  lines  such  as 

host=129.236. 10.55  view=dbdb5  discon=surface,... 

in  whicli  one  specifies  the  Internet  address  of  the  machine  containing  the  database  desired, 
the  name  of  the  database,  and  the  name  or  number  of  the  discontinuity  to  which  the 
extracted  information  should  be  applied. 

Whether  utilizing  the  Internet  connection  or  simply  reading  topography  information 
from  a  local  disk  file,  it  is  necessary  to  use  a  1-D  starting  model  as  a  basis.  The  creation 
of  model  topography  takes  place  as  the  1-D  model  is  stretched  into  2-D.  Trying  to  incor¬ 
porate  topography  into  a  2-D  model  created  in  an  earlier  worksession  will  have  unpredict¬ 
able  results. 
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6.  COMMON  ERRORS  AND  PITFALLS 

Considerable  effort  has  been  made  to  write  the  best  code  possible  given  the  resources 
available  for  this  project.  In  particular,  one  of  the  principal  design  goals  was  to  make  the 
package  as  easy  to  use  and  with  as  seamless  an  interface  to  other  programs  as  is  possible. 
However,  even  with  more  than  10“*  lines  of  code,  the  diverse  demands  of  the  research  and 
analysis  connununity  will  certainly  outstrip  this  package’s  capabilities.  Some  pitfalls  listed 
here  may  seem  silly  given  all  the  other  checks  the  programs  automatically  make,  but  many 
are  rooted  in  the  package’s  internal  architecture.  All  were  addressed  as  resources  permit¬ 
ted. 

(1)  When  using  geotool,  trying  too  narrow  a  velocity  model.  If  the  maximum  separation 
or  receivers  being  viewed  by  geotool  is  10,000  km  and  you  have  a  model  only  7,000  km 
in  breadth,  Xgbm  will  issue  an  error  message. 

(2)  Forgetting  what  rays  you  have  written  out.  It  is  easy  to  adjust  the  takeoff  angles  of 
one  phase  in  the  list,  then  select  another  (de-selecting  the  first  phase  in  the  process),  and 
write  its  results  out.  Unless  you  have  both  phases  selected  when  you  write  the  raytracing 
results  to  file,  your  seismogram  may  contain  the  one  chosen  but  not  the  other. 

(3)  Overwriting  old  seismograms.  This  problem  has  been  largely  solved  in  Version  1.1. 
Earlier  versions  may  give  some  difficulty. 

(4)  Although  Xgbm  has  the  capability  to  display  more  than  one  source  at  a  time,  its 
behavior  is  unpredictable  in  most  cases  when  more  than  one  source  are  handled.  Please 
use  great  caution. 

(5)  Adopting  too  little  model  resolution  when  high  relief  topography  is  to  be  placed  on 
thin  layers.  Xgbm  acts  to  prevent  the  creation  of  triangles  with  unfavorable  aspect  ratios. 
This  problem  has  been  illustrated  in  Section  5.6. 

7.  BUTTON  ACTIONS 

This  section  is  to  provide  a  reference  for  how  Xgbm  responds  to  the  selection  of  its 
buttons.  The  main  menu  bar  consists  of  the  buttons  FILE,  EDIT,  VIEW,  OPTIONS  and 
HELP.  Selection  of  any  of  these  will  cause  a  pulldown  menu  to  appear.  With  the  excep¬ 
tion  of  HELP  the  consequences  of  selecting  a  button  are  detailed  below. 

7.1  FILE  Pulldown  Menu 

INPUT  -  for  reading  in  velocity  models;  causes  pulldown  menu  to  appear. 
INPUTrSTANDARD  -  manages  "Xgbm  Model  Choice"  popup. 
INPUT:USER-DEFINED  -  manages  "User-defined  Models"  popup. 

SAVE  -  for  saving  velocity  model  to  file;  manages  "Xgbm  OutfilePrompt"  popup. 
WRITE  -  toggles  writing  raytracing  results  to  file. 

USE  GIS  -  toggles  use  of  GIS  software  to  input  information  on  topography 
SET  GIS  -  manages  "GIS  Input"  popup. 

PRINT  -  manages  the  "Model  Print"  popup. 
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QUIT  -  halts  program  execution. 

7.2  EDIT  Pulldown  Menu 

MAKE  PHASE  -  for  composing  non-standard  phases;  manages  "Make  Phase"  popup. 
MOVE  KNOTS  -  toggles  ability  to  move  knotpoints 

ADD  KNOTS  -  toggles  ability  to  add  knotpoints  at  location  of  crosshairs  with  the  ’a’ 
key.. 

MODEL  -  for  creating  irregular  discondnuities;  manages  "Edit  Model"  popup. 
PARAMETERS  -  for  changing  parameters  of  single  knots;  manages  "changeVel" 
popup. 

7.3  VIEW  Pulldown  Menu 

SOURCE  -  causes  pulldown  menu  to  appear. 

SOURCE.ADD  -  adds  one  source  to  velocity  model  display. 

SOURCE:DELETE  -  deletes  one  source  from  velocity  model  display. 
SOURCE:DELETE  ALL  -  deletes  all  sources  from  velocity  model  ^splay. 
SOURCE;LOCK  -  toggle  to  freeze  source  at  current  coordinates 
RECEIVER  -  causes  pulldown  menu  to  appear. 

RECEIVER.ADD  -  adds  one  receiver  to  velocity  model  display. 

RECEIVERrADD  STRING  -  for  placing  array;  manages  "Receiver  String"  popup. 
RECEIVER  :DELETE  -  deletes  one  receiver  from  velocity  model  display. 
RECEIVER:DELETE  ALL  -  deletes  all  receivers  from  velocity  model  display. 
TRIANGLES  -  toggle  for  display  of  all  model  triangle  sides. 

CLEAR  RAYS  -  clears  display  of  all  plotted  ray  trajectories. 

FLATTEN  -  toggles  display  between  "flattened"  and  "unflattened’  (spherical). 

COLOR  -  causes  pulldown  menu  to  appear. 

COLOR  ;OFF  -  returns  display  to  plain  background. 

COLOR; Vp  -  background  color  becomes  proportional  to  Vp . 

COLOR:Vs  -  background  color  becomes  proportional  to  v^. 

COLOR.’Rho  -  background  color  becomes  proportional  to  p. 

COORDS  -  for  finding/setting  coordinates;  manages  "coordinates"  popup. 

7.4  OPTIONS  Pulldown  Menu 

PHASE  LIST  -  for  selecting  phases  to  trace;  manages  "Phase  List"  popup. 

COMPUTE  SEISMOGRAM  -  manages  "Xgbm  Seismogram  Computation"  popup. 
QUERY  GEOTOOL  -  sends  IPC  message  called  SelectedWaveforms  to  geotool 
requesting  src/rec  coordinates. 

TRAVEL  TIME  CURVES  -  for  plotting  traveltimes;  manages  "Travel-Time  Curves" 
popup. 
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7.5  Xgbm  Model  Choice  popup 

DEPTH/RADIUS  -  changes  axes’  labeling  of  velocity  and  density  plots. 

KM/DEGREES  -  forces  program  to  interpret  text  entry  as  km/degrees. 

APPLY  -  implements  model  based  on  depth,  breadth  and  resolution  limits  as  set; 
unmanages  "Xgbm  Model  Choice"  popup. 

HIDE  -  unmanages  "Xgbm  Model  Choice"  popup  without  implementing  model  choice. 

7.6  User-defined  Models  popup 

OK  -  program  reads  string  in  Selection  text  widget  and  attempts  to  open 

that  file;  unmanages  "User-defined  Models"  popup.  If  the  file  opening  succeeds 
and  that  file  does  contain  a  valid  model,  that  model  will  be  read  in  and 
displayed;  if  not,  an  error  popup  will  appear. 

FILTER  -  revises  Directories  and  Files  lists  on  the  basis  of  the 
string  in  the  Filter  text  widget. 

CANCEL  -  unmanages  "User-defined  Models"  popup  without  attempting  to  open  and 
read  any  files. 

7.7  Xgbm  OutfiiePrompt  popup 

OK  -  program  attempts  to  write  velocity  model  to  file  in  directory  set  by 

GBWORKENV  environment  and  named  according  to  string  in  text  widget; 
unmanages  "Xgbm  OutfiiePrompt"  popup. 

CANCEL  -  unmanages  "Xgbm  OutfiiePrompt"  popup  without  attempting  to  open  file. 


7.8  Make  Phase  popup 

BEGIN  -  program  calculates  and  plots  a  ray  segment  beginning  at  the 
source  and  terminating  at  the  first  discontinuity  the  ray  encounters. 

The  ray  type  {P  or  5 )  is  determined  by  the  current  state  of  the 
P/S  radio  button. 

TRANSMIT  -  program  calculates  and  plots  the  next  ray  segment  beginning 
as  a  transmission  through  the  discontinuity  last  hit  and  continuing  until 
a  new  discontinuity,  the  free  surface,  or  a  model  boundary  is  encountered. 
The  new  segment’s  ray  type  is  set  by  the  current  state  of  the 
P/S  radio  button. 

REFLECT  -  program  calculates  and  plots  the  next  ray  segment  beginning 
as  a  reflection  from  the  discontinuity  last  hit  and  continuing  until 
a  new  discontinuity,  the  free  surface,  or  a  model  boundary  is  encountered. 
The  new  segment’s  ray  type  is  set  by  the  current  state  of  the 
P/S  radio  button. 

END  -  causes  program  to  register  phase  internally  and  to  append  a  phase  name 
corresponding  to  string  in  Phase  Name  text  widget  to  phase  list 
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found  in  "Phase  List"  popup. 

HIDE  -  unmanages  "Make  Phase"  popup. 


7.9  Edit  Model  popup 

SET  -  reads  current  values  found  in  the  text  widgets  of  this  popup  and  updates 
currently  selected  knotpoints  and  triangles  explicitly  according  to  these  values. 

ADD  -  reads  current  values  found  in  the  text  widgets  of  this  popup  and  updates 
currently  selected  knotpoints  and  triangles  by  incrementing  their  current  values  by 
the  text  widget  entries. 

MULTIPLY  -  reads  current  values  found  in  the  text  widgets  of  this  popup  and  updates 
currently  selected  knotpoints  and  triangles  by  scaling  their  current  values  by  the 
text  widget  entries. 

CLEAR  -  cancels  current  knot  segment  creation. 

CLOSE  -  program  closes  loop  of  tracing  by  connecting  last  point  with  beginning  point, 
as  long  as  the  created  segment  does  not  cross  earlier  ones. 

ADD  DISCON  -  program  creates  discontinuity  along  tracing. 

ADD  KNOTS  -  program  creates  string  of  knots  or  repositions  near  knots  along  the 
tracing. 

HIDE  -  unmanages  "Edit  Model"  popup. 

7.10  changeVel  popup 

SET  -  causes  program  to  modify  properties  of  knot  according  to  values  in 
this  popup’s  text  widgets. 

HIDE  -  unmanages  "changeVel"  popup. 


7.11  Receiver  String  popup 

APPLY  -  causes  program  to  place  a  string  of  receivers  in  pattern  specified 
in  text  widgets.  See  Section  5.2.2. 

CANCEL  -  unmanages  "Receiver  String"  popup. 


7.12  coordinates  popup 

SET  -  causes  program  to  place  source  and/or  receiver  at  coordinates  cf 

text  widget  entries  and  unmanages  popup.  If  more  than  one  source  or  receiver 
are  present  in  the  display,  only  the  most  recently  added  will  be  repositioned. 

KM  -  toggle  to  force  program  to  interpret  text  widget  entries  in  this 

popup  and  in  "Receiver  String"  popup  as  kilometers  or  as  degrees.  Default 
position  is  ’on’  (kilometers). 

RELATIVE  -  toggle  to  force  program  to  interpret  text  widget  entries  in 
this  popup  as  relative  to  source  or  relative  to  velocity  model 
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coordinate  system  (  default ).  HIDE  -  unmanages  the  "coordinates "  popup. 


7.13  Phase  List  popup 

FORWARD  -  program  reads  minimum  takeoff  angle  from  list  entries, 
increments  that  number  by  value  in  text  widget  to  right  of  BACK 
button,  revises  list  entries  and  text  widget  entries, 
and  plots  a  single  ray  of  that  takeoff  angle  if  possible. 

BACK  -  program  reads  minimum  takeoff  angle  from  list  entries, 

decrements  that  number  by  value  in  text  widget  to  right  of  BACK 
button,  revises  list  entries  and  text  widget  entries, 
and  plots  a  single  ray  of  that  takeoff  angle  if  possible. 

ADD  -  program  reads  string  in  Phase  Code  text  widget  and  compares  the 
string  to  phase  list.  If  already  there,  program  manages  error  popup, 
otherwise  appends  string  to  bottom  of  phase  list. 

INPUT  -  for  importing  phase  description  files;  manages 
"Input  User-Defined  Phases"  popup. 

SAVE  -  for  writing  a  phase  description  file;  manages  "Save  Selected  Phases" 
popup. 

DELETE  -  delete  selected  entries  from  phase  list. 

AUTO  -  invokes  primitive  search  routine  for  selected  phases.  Initial  takeoff 
angles  of  selected  phases  must  be  so  chosen  that  raypaths  bracket 
receiver  location(s).  At  least  one  receiver  must  be  displayed. 

ALL  -  select  all  phases  in  phase  list. 

APPLY  -  trace  all  rays  of  selected  phases.  If  WRITE  toggle  button  (from 
FILE  main  menu  pulldown)  is  ’on! ,  raytracing  results  will  be 
written  to  file. 

HIDE  -  unmanages  "Phase  List"  popup. 


7.14  Xgbm  Seismogram  Computation  popup 

OPTION  -  sets  method  of  computing  Gaussian  beam  parameter  e  according 
to  Weber,  (1988a). 

ANELASTIC/ELASTIC  -  toggle  controls  whether  t*  operator  is  used  or  not. 

KUEPPER  SIGNAL/USER-DEFINED  -  toggle  controls  what  type  of  source-time 
function  is  used.  If  KUEPPER  SIGNAL  is  selected,  the  "Kuepper  signal" 
popup  is  managed;  if  USER-DEFINED,  the  "Xgbm  Src-Time  Funct  Input" 
popup  is  managed. 

EXPLOSION/LINE  SOURCE/DOUBLE  COUPLE  -  sets  source  type;  selecting 
DOUBLE  COUPLE  will  cause  the  "Xgbm  Focal  Mechanism"  to  be  managed. 

SET  LENGTH  -  for  explicitly  controlling  time  parameters  of  synthetic 
calculation;  manages  the  "Seismogram  length"  popup. 

RAYFILE  NAME  -  for  setting  name  of  raytracing  output  file;  manages  the 
"Xgbm  Rayfile  Name  Input"  popup. 
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COMPUTE  -  initiates  sequence  to  compute  synthetic.  Program  inteiprets 
settings  of  widgets  in  this  popup  (and  their  associated  popups), 
constructs  a  message  to  GBseis .  Message  is  dispatched  according  to 
operating  mode.  See  Section  5.4. 

CHECK  -  for  checking  proximity  of  rays  to  receivers;  manages  the 
"Xgbm  Information"  popup. 

HIDE  -  unmanages  "Xgbm  Seismogram  Computation"  popup. 


7.15  Travel-Time  Curves  popup 

CLEAR  -  clears  traveltime  display. 

AUTO  CLEAR  -  toggle  to  enable  automatic  clearing  of  display.  When  'off 
(  default ),  program  superimposes  curves  from  different  models  and  source 
depths.  When  ’on’,  display  is  cleared  each  time  before  rays  are 
retraced. 

PRINT  -  manages  the  "Model  Print"  popup. 

HIDE  -  unmanages  the  "Travel-Time  Curves"  popup. 


7.16  Input  User-Defined  Phases  popup 

APPLY  -  read  string  in  Filename  text  widget;  attempt  to  open  file  of 
that  name;  if  successful,  read  file  and  revise  phase  list  accordingly. 
CANCEL  -  unmanages  "Input  User-Defined  Phases"  popup  without  attempting  to 
open  any  files. 


7.17  Save  Selected  Phases  popup 

APPLY  -  read  string  in  Filename  text  widget;  attempt  to  open  file  of 

that  name;  if  successful,  write  content  of  selected  entries  in  phase  list 
to  file. 

CANCEL  -  unmanages  "Save  Selected  Phases"  popup  without  attempting  to 
open  any  files. 

7.18  Kuepper  signal 

HIDE  -  unmanages  "Kuepper  signal"  popup.  These  text  widgets  will  be  read 

by  program  when  APPLY  (from  "Xgbm  Seismogram  Computation")  is  selected 
if  KUEPPER  SIGNAL  is  then  ’on. 


7.19  Xgbm  Src-Time  Fund  Input  popup 

HIDE  -  unmanages  "Xgbm  Src-Time  Funct  Input"  popup.  The  string  in  the 
Filename  text  widget  will  only  be  read  by  the  program  when 
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APPLY  (from  "Xgbm  Seismogram  Computation")  is  selected  if 
USER-DEFINED  is  then  ‘on. 


7.20  Xgbm  Focal  Mechanism  popup 

HIDE  -  unmanages  "Xgbm  Focal  Mechanism"  popup.  These  sliders  will  be  used 
by  program  when  APPLY  (from  "Xgbm  Seismogram  Computation")  is  selected 
if  DOUBLE  COUPLE  is  currently  selected. 


7.21  Seismogram  length  popup 

ACTIVATE  -  toggle  to  control  use  of  information  in  the  three  text 
widgets  of  this  popup.  If  toggle  is  ’on’,  the  text  widgets  may  be 
edited,  and  this  information  will  be  used  the  next  time  the 
APPLY  (from  "Xgbm  Seismogram  Computation")  button  is  selected. 

If  toggle  is ‘off,  widgets  cannot  be  edited,  and  the  program  will 
ignore  these  entries. 

HIDE  -  unmanages  "Seismogram  length"  popup. 

7.22  Xgbm  Rayfile  Name  Input  popup 

HIDE  -  umnanages  "Xgbm  Rayfile  Name  Input"  popup.  If  WRITE  toggle  (from 
FILE  pulldown)  is  ’on’,  program  will  read  string  from  text  widget  in 
this  popup  and  attempt  to  write  results  to  file  of  that  name  in  directory 
set  by  GBWORKENV  environment. 


7.23  Xgbm  Information  popup 

OK/HIDE  -  unmanages  "Xgbm  Information"  popup. 


7.24  GIS  Input 

HIDE  -  unmanages  "GIS  Input"  popup. 

8.  KNOWN  BUGS 

These  listed  here  are  well  recognized  shortcomings,  but  unfortunately  they  generally 
cannot  be  addressed  under  the  present  system  architecture.  If  the  system  is  ever 
redesigned,  effon  will  be  made  correct  them. 

(1)  When  the  velocity  model  is  shown  in  unflattened  mode,  the  raypaths  are  displayed 
incorrectly.  This  display  is  based  on  rays  traced  through  the  flattened  model.  When  rays 
are  transformed  for  the  unflattened  display,  they  do  not  always  meet  the  triangle  sides. 
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The  internal  calculation  is  correct,  however,  and  calculated  traveltiines  and  syrithetic 
seismograms  are  perfectly  valid  in  both  flattened  and  unflattened  display  mode.  This  irk¬ 
some  property  diminishes  somewhat  with  model  resolution. 

(2)  When  in  an  IPC  mode,  Xgbm  uses  the  azimuth  of  the  first  station  in  the  IPC  message 
from  geotool  to  calculate  its  seismograms  for  all  stations.  This  particular  value  can  be 
overridden  in  the  "Focal  Mechanism"  popup,  but  it  is  still  applied  to  all  receivers  without 
regard  to  their  varying  geometry.  There  is  no  satisfactory  way,  as  yet,  to  project  3-D  data 
onto  a  2-D  model  with  this  system. 

(3)  There  is  currently  no  elegant  way  to  terminate  GBseis  when  it  is  running  in  IPC  mode 
under  ISIS.  In  Unix,  one  may  use  the  kill  command  if  one  knows  GBseis'  process  id 
number,  or  one  may  bring  it  to  the  foreground  and  kill  it  by  typing  the  interrupt  key. 
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Appendix  A.  IPC  Message  Formats 

Below  is  a  table  of  messages  exchanges,  followed  by  a  detailed  description  of  its 
contents. 


name 

originator 

recipient 

contents 

1.  SelcctedWaveforms 

Xgbm 

geotool 

src/rec  geometiy  request 

2.  SelectedWaveforms 

geotool 

Xgbm 

src/rec  geometiy 

3.  Dogbseis 

Xgbm 

GBseis 

computation  parameters 

4.  Donegbseis 

GBseis 

Xgbm 

output  database  name 

5.  wfdisc  3.0 

Xgbm 

geotool 

syn  database  name 

6.  Errorgbseis 

GBseis 

Xgbm 

error  string 

7.  Timegbseis 

- 

GBseis 

traveltime  request 

8.  GBseistimes 

GBseis 

- 

traveltime(s) 

9.  Quitgbseis 

- 

GBseis 

quit  command 

The  following  are  the  message  formats.  Regular  type  represents  that  part  of  the  mes¬ 
sage  required  of  all  messages  of  that  name  and  is  used  by  the  program  to  parse  the  mes¬ 
sage.  Italic  type  is  that  part  of  the  message  unique  to  each  transmission.  The  order  of 
elements  in  (2)  is  critical;  that  of  (3)  is  not.  In  message  (3),  the  rayfile  name  must  be  pro¬ 
vided. 


(1)  ""  (empty  string) 

(2)  "num=  number  of  wav^orms 
sta=  'sta  (traceiy 

chan=  'chan  (tracel)’ 

lat=  lat(sta-tracel ) 

lon=  lon(sta- tracel) 

samprate=  samprate(  trace  1 ) 

tl=  beginning  epochal  time( tracel) 

t2=  ending  epochal  time( tracel) 

olat=  origin-latitude 

olon=  origin-longitude 

depth=  origin-depth 

otime=  origin  epochal  time 

narr=  number  of  arrivals( trace  1 ) 

phase=  ’first  phase  name( tracel)’ 

time=  first  arrival  time( tracel) 

phases  'second  phase  name( tracel)’ 

times  second  arrival  time( tracel)  ..." 

(3)  "rayfiles  "ray tracing  input  filename" 
d.ix=" output  file  prefix  name" 

Afi\e=" output  directory  name" 
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stfunc="  name  of  file  containing 'soUrce-time  function" 

is=number  of  points  in  time  series 

dt=sampling  interval  in  seconds 

trmn^ofifset  time  from  origin 

\Ttd=reduction  velocity  {km! sec) 

i=duration  of  Kuepper  signal  (Section  5.4) 

n=shape  of  Kuepper  signal  (Section  5.4) 

ndisp=0/7  -  ignorelinclude  dispersion 

ipu^/i/2  -  line  sourcelpoint  source/double  couple 

m=ll2l3l4l6l7l8  -  Weber  option  number  1.2^151416171819 

ngb=Mse  every  ngb’th  ray  in  calculation 

ne{v=number  of  effective  beamwidths  to  include 

gl=beamwidth  for  option  6. 

epslf=ei 

eps2f=€2 

stn=strike  of  focal  mechanism 
6xp=dip  of  focal  mechanism 
T2k=rake  of  focal  mechanism 
a.zi=station  azimuth  for  focal  mechanism 
qtnin=/ower  half  of  lower  limit  on  q  taper 
qt=upper  half  of  lower  limit  on  q  taper 
qtx^lower  half  of  upper  limit  on  q  taper 
qmzx^upper  half  of  upper  limit  on  q  taper 
ola.t=origin  latitude 
o\on=origin  longitude 
otime=origin  epochal  time 
nr=number  of  receivers 

de\X3i=distance  to  first  receiver  (degrees),  to  second  receiver  ....  to  nr’th  receiver" 

(4)  "  synthetic _seismogram_database  jtrefix" 

(5)  "prefix=  synthetic_seismogram_database jjrefix" 

(6)  "string  describing  error" 

(7)  "rayfile=  "raytracing  outfilename" 
phase=  "phase  name  (<=  32  characters)" 
nr=  number  of  receivers 

de\X3i=distance  to  first  receiver  (degrees),  to  second  receiver  ...,  to  nr’th  receiver 
nefv=  number  of  effective  beamwidths" 

(8)  "times=  timejrec.l,  time_rec.2,  ...time_rec.nr" 

(9)  ""  (empty  string) 
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Appendix  B.  Fite  Formats 


times.out  -  This  file  is  opened  by  Xgbm  at  the  same  time  raytracing  results  are  written  to 
file.  It  currently  consists  of  six  columns:  phase  name,  distance  (degrees),  source  depth 
(km),  traveltime  (seconds),  slowness  (seconds/degree)  and  t  . 


rays.out  -  This  is  the  name  of  the  default  raytracing  output  file  written  in  binary  by  Xgbm 
and  read  by  GBseis .  The  name  may  be  changed  by  the  user  at  run  time.  The  header  to 
the  file  consists  of  five  numbers: 

double  —  X  coordinate  of  source 
double  ”  z  coordinate  of  source 
double  “  Vp  at  source  coordinates 
double  —  Vj  at  source  coordinates 
double  —  p  at  source  coordinates 

This  is  followed  by  a  block  of  numbers  for  each  ray.  Each  block  consists  of: 
int  —  indicates  position  in  order  of  phases  to  be  computed 
float  --  rate  of  change  of  starting  angle  between  rays  of  this  phase 
int  —  raytype  at  source:  1  for  F ,  3  for  SV,  5  for  SH 
float  ”  takeoff  angle  (degrees) 
float  —  horizontal  slowness  at  endpoint 
float  —  X  component  of  unit  tangent  vector  at  endpoint 
float  “  z  component  of  unit  tangent  vector  at  endpoint 
float  -  X  coordinate  of  endpoint 
float  “  z  coordinate  of  endpoint 
float  "  velocity  at  endpoint 

float  —  velocity  gradient  perpendicular  to  ray  tangent  at  endpoint 
float  —  velocity  gradient  parallel  to  ray  tangent  at  endpoint 
float  —  p  at  endpoint 
float  —  traveltime 

float  —  real  part  of  product  of  reflection/transmission  coefficients  along  ray 

float  —  imaginary  part 

float  -  q  1  given  at  ray  endpoint 

float  —  p  1  given  at  ray  endpoint 

float  —  ^2  given  at  ray  endpoint 

float  -  P2  given  at  ray  endpoint 

float  -  Ej  -  real  pan  of  beam  parameter  e 

float  —  £2  -  imaginary  part 

float  -  number  of  caustics  touched  by  ray  (caustics  of  line-source-field) 

float  —  transversal  spreading  (point  source) 

float  -  reciprocal  of  square  of  beamwidth  at  main  frequency 

float  —  absorption  parameter  given  at  ray  endpoint 

float  -  Q-factor  at  ray  endpoint 

float  -  product  of  th/thti  along  ray 

float  -  real  part  of  horizontal  transfer  function 
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float  -  imaginary  part 
float  —  real  part  of  vertical  transfer  function 
float  -  imaginary  part 
char  [31  bytes]  —  phase  name 
Refer  to  Weber  (1988a)  for  symbol  definitions. 


dbr.GB_input  -  This  input  file  name  is  fixed.  The  contents  of  the  file  should  be  a  single 
string  corresponding  to  the  format  of  the  Dogbseis  IPC  message  in  Appendix  A.  This  file 
is  written  by  Xgbm  and  read  by  GBseis  only  when  the  package  is  run  in  non-IPC  mode. 


velocity  model  input  -  While  there  is  no  rigid  naming  convention  for  these  files,  the 
Xgbm  popup  for  inputing  such  a  file  is  designed  to  find  files  ending  in  ".gb"  faster.  Each 
velocity  model  input  file  consists  of  columns  of  figures  corresponding  to  depth,  Vp ,  ,  p, 

(2  a  respectively.  Two  lines  for  the  same  depth  indicate  a  velocity  discontinuity. 

One  should  place  lines  with  strings  "mantle",  "outer-core"  and  "inner-core"  between  tne 
lines  representing  these  discontinuities.  See  Appendix  C. 


velocity  model  output  -  These  are  binary  files  intended  for  input  by  Xgbm .  The  header 
to  the  file  consists  of  six  numbers: 

int  "  set  equal  to  376482  to  indicate  model  stored  in  binary  format 
int  -  layer  index  of  mantie-  crust  boundary 
int  “  layer  index  of  core-mantle  boundary 
int  "  layer  index  of  inner  core-outer  core  boundary 
int  —  number  of  knots  in  model 
int  "  number  of  triangles  in  model 
For  each  knot,  there  follows  a  block  with  the  following  format: 
float  —  X  coordinate  of  knot 
float  —  z  coordinate  of  knot 
float  ~  Vp 
float  -  Vj 
float  -  p 

For  each  triangle,  there  are  first  blocks  of  this  format: 

int  “  index  of  triangle’s  first  knot  (counterclockwise) 

int  —  index  of  triangle’s  second  knot  (counterclockwise) 

int  —  index  of  triangle’s  third  knot  (counterclockwise) 

int  —  index  of  triangle’s  first  neighboring  triangle  (counterclockwise) 

int  —  index  of  triangle’s  second  neighboring  triangle  (counterclockwise) 

int  —  index  of  triangle’s  third  neighboring  triangle  (counterclockwise) 

int  -  type  of  discontinuity  between  this  and  first  neighboring  triangle 

int  —  type  of  discontinuity  between  this  and  second  neighboring  triangle 

int  —  type  of  discontinuity  between  this  and  third  neighboring  triangle 

float  —  (2  a  for  triangle 

float  ”  G  p  for  triangle 
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int  —  code  for  crust,  mantle,  outer  coie,  and  inner  core 
char  —  boolean  code  for  whether  that  triangle  was  selected  or  not 
and  then  blocks  of  this  format: 
double  —  B(Vp )  /  dx 
double  —  3(v,)  /  dx 
double  —  9p  /  dx 
double  —  d(Vp )  /  dz 
double  —  3(Vj )  /  dz 
double  "  3p  /  dz 

The  code  for  neighboring  triangles  and  type  of  discontinuity  uses  the  following  conven¬ 
tion:  if  the  triangle  is  on  the  border  of  the  model,  the  index  value  for  the  neighboring  tri¬ 
angle  is  set  to  333333333.  If  there  are  receivers  located  on  that  side,  the  neighboring  tri¬ 
angle  is  multiplied  by  -1.  The  first  neighbor  is  located  on  the  side  connecting  the  first  and 
second  knots,  etc.  If  the  discontinuity  between  the  triangle  and  its  neighbor  is  in  the 
second  derivative  of  velocity  only,  the  type  is  set  to  zero.  If  the  discontinuity  is  in  the 
first  derivative  of  velocity,  the  type  is  set  to  the  program’s  internal  index  of  that  discon¬ 
tinuity.  If  the  type  is  222222,  the  triangle  borders  the  free  surface. 


source-time  function  -  These  files  are  free  format  ASCII  files  and  should  contain  only 
figures  representing  the  time  series  of  the  source-time  function.  The  file  may  be  read  in 
using  the  USER-DEFINED  option  when  setting  up  the  seismogram  calculation  in  Xgbm . 


xgb.rgb  -  This  file  lists  the  red-green-blue  ».,ensities  for  the  colors  used  in 
velocity/density  displays.  Each  line  contains  an  integer  triplet  ranging  from  0  to  255.  The 
file  is  read  until  the  hardware-dependent  number  of  colors  limit  is  met  or  the  end-of-ifle  is 
encountered. 


GIS  topography  input  -  Files  of  this  format  are  used  to  impose  topography  on  velocity 
model  discontinuities.  The  most  common  such  file,  Xgbm.gis,  is  generated  by  the  routine 
gc_raster,  but  the  user  may  input  any  similar  file  via  the  "GIS  Input"  popup’s  text  widget. 
(An  example  file  GERESS_south.topo  is  include  in  the  vmodels  subdirectory.)  The  file 
may  have  one  or  more  blocks  of  lines.  Each  block  consists  of  a  header  line  composed  of 
a  string  to  identify  the  discontinuity  and  an  integer  to  indicate  the  number  of  lines  contain¬ 
ing  x-z  coordinate  pairs  to  follow.  That  is: 
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string_identifier.block_l  npts.block_l 
xl(l)  zl(l) 
xl(2)  zl(2) 

xl(npts.block_l)  zl(npts.block_l) 

string_identifier.block_2  npts.block_2 
x2(l)  z2(l) 
x2(2)  z2(2) 

x2(npts.blcx:k_2)  z2(npts.block_2) 


The  possibilities  for  the  string_identifier  are  surface,  moho,  CMB,  ICOC,  and  discon=n, 
where  «  is  an  integer  to  identify  the  discontinuity.  In  a  1-D  model,  the  surface  would  be 
n=0,  the  first  discontinuity  below  that  would  be  /i=l,  etc.,  so  that  entering 

surface  100 
and 

discon=0  100 

are  equivalent.  For  correct  parsing  to  take  place,  it  is  essential  that  no  spaces  be  between 
"discon",  "="  and  the  integer. 

Under  the  present  scheme,  the  x  coordinate  is  given  in  degrees,  and  the  z  coordinate,  in 
kilometers.  The  z  coordinate  increases  with  depth,  so  to  impose  surface  topography  above 
sea  level,  a  negative  z  value  must  be  used.  This  curious  mixture  of  units  makes  little 
sense  if  one  is  working  only  near  the  surface,  but  since  discontinuities  can  occur  at  a  wide 
variety  of  depths,  it  is  more  uniform  to  express  the  coordinates  in  this  way. 
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Appendix  C.  Velocity  Models 

The  standard  global  models  distributed  with  the  software  package  are  derived  from 
published  sources,  either  as  such  or  as  derived  from  traveltime  tables. 


abbreviation 

name 

reference 

jb 

herrin.abr 

herrin.orig 

1066a 

1066b 

prem 

iaspei91 

pwdk 

afis 

sp6 

Jeffreys-Bullen  tables 
Herrin  tables 
Herrin  tables 
Model  1066A 
Model  1066B 
PREM 

lASPEI  1991  tables 
Model  PWDK 
Model  AFLS 
Model  SP6 

Jeffreys  and  B alien,  1940 

Herrin  et.  al.,  1968 

Herrin  et.  al.,  1968 

Gilbert  and  Dziewonski,  1975 
Gilbert  and  Dziewonski,  1975 
Dziewonski  and  Anderson,  1984 
Kennett,  1991 

Weber  and  Davis,  1990 
Schlittenhardt,  1991 

Morelli  and  Dziewonski,  1993 

The  abr  and  orig  following  herrin  refer  to  abridged  (smoothed  over  depths  where  the  velo¬ 
city  gradient  was  small)  and  original,  respectively.  In  those  instances  where  a  published 
model  consisted  only  of  seismic  velocities,  values  for  density  were  interpolated  from 
PREM  and  values  for  attenuation  were  interpolated  from  the  Q  models  of  Masters  and 
Gilbert  (1983).  The  exception  to  this  is  SP6,  for  which  the  Q  values  were  interpolated 
from  PREM.  Model  AFLS  is  PREM  with  a  crustal  model  appropriate  for  Pahute  Mesa 
and  an  upper  mantle  (depth  <  1271  km)  Q  structure  from  Archambeau  et  ah,  (1969). 

The  global  files  are  all  stored  in  the  /vmodels  subdirectory  in  a  series  of  files  all 
prefixed  with  "GB."  (Your  GBMODENV  environment  should  be  pointing  to  Ivmodels.) 
Each  file  consists  of  columns  of  figures  corresponding  to  depth,  v^,  v^,  p,  and  Qp, 
respectively.  Two  lines  for  the  same  depth  indicate  a  velocity  discontinuity.  Occasion¬ 
ally,  one  finds  lines  with  strings  like  "mantle",  "outer-core"  and  "inner-core"  between  lines 
of  the  same  depth.  These  are  used  by  the  program  to  create  an  internal  representation  of 
phases. 

It  is  possible  to  create  one’s  own  model  with  a  file  in  this  format.  The  program  can 
read  this  personal  model  in  in  one  of  two  ways.  If  you  expect  to  use  the  model  only 
occasionally,  the  easiest  way  is  to  read  it  in  as  a  user-defined  model,  as  explained  in  Sec¬ 
tion  5. 1.1.2.  A  riskier  way  is  to  add  it  to  the  permanent  list.  This  should  be  done  only 
by  programmers  experienced  with  X-Windows.  First,  be  certain  your  model  file  is  in 
the  Ivmodels  subdirectory.  Next  edit  the  XgbmVel  X- resource  file  in  the  XI 1  subdirectory. 
Search  for  the  string  "globalSW.globals.items".  There  should  be  a  list  of  models  there. 
Add  your  model  name,  being  certain  to  match  the  string  to  your  file  name.  Now  increase 
the  integers  in  the  two  lines  above,  "globalSW.globals.itemCount"  and 
"globalSW.globals.visibleltemCount"  by  the  number  of  models  you  have  added. 

The  list  of  regionals  may  also  be  altered.  The  displayed  list  is  derived  from  the  file 
GB.regionals  in  the  /vmodels  subdirectory.  Each  line  in  the  file  contains  information 
about  a  two-layer  model  over  a  half-space.  The  parameters  are  in  the  following  order:  top 
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layer  thickness,  bottom  layer  thickness,  v^(top),  (bottom),  Vp  (mantle),  Vj(top), 
(bottom),  Vj  (mantle),  p(top),  p(bottom),  p(mantle),  2a(all),  GpCall),  and  identification 
string.  To  add  your  model,  simply  edit  this  file  and  add  a  new  line  with  its  parameters. 
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A  complete  description  of  the  CSS  3.0  format  can  be  found  in  Anderson  et  al.  (1990).  Included 
here  are  tables  only  for  v^disc,  origin,  and  arrival  tables.  The  .wfiles,  which  the  wfdisc  files  describe, 
are  always  written  by  GBseis  in  t4,  i.e.,  IEEE  single  precision  floating  point  numbers. 


Relation: 

Description: 

arrival 

Summary  information  on  a  seismic  arrival 

attribute 

name 

field 

no. 

storage 

type 

external 

format 

character 

positions 

attribute 

description 

sta 

1 

c6 

a6 

1-6 

station  code 

time 

2 

f8 

fl7.5 

8-24 

epoch  time 

arid 

3 

i4 

i8 

26-33 

arrival  id 

jdate 

4 

i4 

i8 

35-42 

Julian  date 

stassid 

5 

i4 

i8 

44-51 

stassoc  id 

chanid 

6 

i4 

i8 

53-60 

instrument  id 

chan 

7 

c8 

a8 

62-69 

channel  code 

iphase 

8 

c8 

a8 

71-78 

reported  phase 

stype 

9 

cl 

al 

80-80 

signal  type 

deltim 

10 

f4 

f6.3 

82-87 

delta  time 

azimuth 

11 

f4 

f7.2 

89-95 

observed  azimuth 

delaz 

12 

f4 

n.2 

97-103 

delta  azimuth 

slow 

13 

f4 

f7.2 

105-111 

observed  slowness  (s/deg) 

delslo 

14 

f4 

f7.2 

113-119 

delta  slowness 

ema 

15 

f4 

n.2 

121-127 

emergence  angle 

rect 

16 

f4 

f7.3 

129-135 

rectilinearity 

amp 

17 

f4 

flO.l 

137-146 

amplitude,  instrument  corrected,  nm 

per 

18 

f4 

(7.2 

148-154 

period 

logat 

19 

f4 

n.2 

156-162 

log{amp/per) 

clip 

20 

cl 

al 

164-164 

clipped  flag 

fm 

21 

c2 

a2 

166-167 

first  motion 

snr 

22 

f4 

flO.2 

169-178 

signal  to  noise  ratio 

qual 

23 

cl 

al 

180-180 

signal  onset  quality 

auth 

24 

cl5 

al5 

182-196 

source/originator 

commid 

25 

i4 

i8 

198-205 

comment  id 

Iddate 

26 

date 

al7 

207-223 

load  date 

D-1 


Relation: 

Description: 

origin 

Data  on  event  location  and  confidence  bounds 

attribute 

name 

held 

no. 

storage 

type 

external 

format 

character 

positions 

attribute 

description 

lat 

1 

f4 

19.4 

1-9 

estimated  latitude 

Ion 

2 

f4 

19.4 

11-19 

estimated  longitude 

depth 

3 

f4 

19.4 

21-29 

estimated  depth 

time 

4 

18 

117.5 

3147 

epoch  time 

orid 

5 

i4 

18 

49-56 

origin  id 

evid 

6 

i4 

i8 

58-65 

event  id 

jdate 

7 

i4 

i8 

67-74 

Julian  date 

nass 

8 

i4 

i4 

76-79 

number  of  associated  phases 

ndef 

9 

i4 

i4 

81-84 

number  of  locating  phases 

ndp 

10 

i4 

i4 

86-89 

number  of  depth  phases 

gm 

11 

i4 

i8 

91-98 

geographic  region  number 

sm 

12 

i4 

18 

100-107 

seismic  region  number 

etype 

13 

c7 

a7 

109-115 

event  type 

depdp 

14 

14 

19.4 

117-125 

estimated  depth  from  depth  phases 

dtype 

15 

cl 

al 

127-127 

depth  method  used 

mb 

16 

14 

17.2 

129-135 

body  wave  magnitude 

mbid 

17 

i4 

18 

137-144 

mb  magid 

ms 

18 

14 

17.2 

146-152 

surface  wave  magnitude 

msid 

19 

i4 

i8 

154-161 

ms  magid 

ml 

20 

14 

17.2 

163-169 

local  magnimde 

mlid 

21 

i4 

i8 

171-178 

ml  magid 

algorithm 

22 

cl5 

al5 

180-194 

location  algorithm  used 

auth 

23 

cl5 

al5 

196-210 

source/originator 

commid 

24 

i4 

ig 

212-219 

comment  id 

Iddate 

25 

date 

al7 

221-237 

load  date 

Relation: 

Description. 

wfdisc 

Waveform  file  header  and  descriptive  information 

attribute 

name 

field 

no. 

storage 

type 

external 

format 

character 

positions 

attribute 

description 

sta 

1 

c6 

a6 

1-6 

station 

chan 

2 

c8 

a8 

8-15 

channel 

time 

3 

f8 

fl7.5 

17-33 

epoch  time  of  first  sample  in  file 

wfid 

4 

i4 

i8 

35-42 

waveform  id 

chanid 

5 

i4 

i8 

44-51 

channel  operation  id 

jdate 

6 

i4 

i8 

53-60 

Julian  date 

endtime 

7 

f8 

fl7.5 

62-78 

lime+(iisamp-  l)/sam  prate 

nsamp 

8 

i4 

i8 

80-87 

number  of  samples 

samprate 

9 

f4 

fll.7 

89-99 

sampling  rate  in  samples/sec 

calib 

10 

f4 

fl6.6 

101-116 

nominal  calibration 

calper 

11 

f4 

fl6.6 

118-133 

nominal  calibration  period 

ins  type 

12 

c6 

a6 

135-140 

instrument  code 

segtype 

13 

cl 

al 

142-142 

indexing  method 

datatype 

14 

c2 

a2 

144-145 

numeric  storage 

clip 

15 

cl 

al 

147-147 

clipped  flag 

dir 

16 

c64 

a64 

149-212 

directory 

dfile 

17 

c32 

a32 

214-245 

data  file 

foff 

18 

i4 

ilO 

247-256 

byte  offset 

commid 

19 

i4 

i8 

258-265 

comment  id 

Iddate 

20 

date 

al7 

267-283 

load  date 

